How to Write Documentation That's Actually Useful

Now more than ever we need well-documented code. Here are four ways to make sure your applications make sense to humans as well as to computers.

Programmers love to write code, but they hate to write documentation. Developers always want to read documentation when they inherit a project, but writing it themselves? Feh! How common is this? A recent GitHub survey found that "incomplete or outdated documentation is a pervasive problem," according to 93 percent of respondents. Yet 60 percent of contributors to the open source code repository say they rarely or never contribute to documentation. Their reasoning, for both the open source projects and their own applications? A common attitude that "documentation is for 'lusers' who don't write good code!"

That's not a stance your business can afford to adopt. Most businesses live and die by their software. If you're a developer or application manager and you don't know what's actually going on in your code, just how stable can your business really be?

Let's get specific. The "truck factor" (or "bus factor") is the minimal number of developers who have to be hit by a truck (or quit) before a project is incapacitated. If your top programmer was run over by the proverbial beer truck, how well could your company pick up the pieces and continue with the project? Evidence suggests badly. A 2016 IEEE paper found that out of 133 popular GitHub projects, 65 percent had a truck factor of two or fewer. Developers rarely assert that everything on their project is well documented, and they rarely claim that everyone knows the details because of awesome team communication. It's far more common to hear feedback like, "Who has time to document everything?"...