Skip to main content

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?"

It is a truth universally acknowledged that a developer in possession of a good program must be in want of good documentation.

Jane Austen...in an alternate universe

In contrast, CIOs and other C-level executives may think everything is under control. In a research study commissioned by Enterprise.Nxt, 57 percent of 106 respondents said a project that loses its primary developer would function just fine, and 36 percent felt they could cope with minor disruption. Many of these CxOs share a belief that a good project manager can keep software projects on track to delivery. For example, wrote one, thanks to project management, "nothing is done without documentation. We'd have access to all their files and emails. Information is shared between everyone. No one hogs information."

Perhaps it's heartening to know the boss has faith in the development and operations staff, but top-down project management goes just so far. Email archives, code backups, SharePoint, and Microsoft Project are all fine and dandy for describing a program's surface plan, but they don't help much with the code muscles and bones and the comments that bind them.

One exec admitted that he'd break into a sweat if his lead developer disappeared: "Other people can step in, but losing the person most involved? We have playbooks; we have people serving as cross-trained backups. But it's hard to replace the one person who's been front and center."

Still, if you want your software to be truly useful, you do need to document applications and interrelated systems. And it's not enough to write documentation. The documentation has to be good, or developers and users will ignore it. Kathy Sierra, the well-known Java author, once said, "If you want them to RTFM, make a better FM." She's right.

Whether it's a sexy new project or a legacy application, we still need code documentation that goes beyond read.me files containing, "To be written later." How do you improve code documentation? Here are some suggestions, moving from the general to the specific.

Make documentation part of the development process

Don't put off commenting the code. In many companies, developers see their primary job as writing, debugging, and maintaining code. Documentation can be a long way down on management and developers' own to-do lists. All too often, once an application works, programmers are pressured to move onto the next project. They might barely have time to clean the Post-It notes off their desks from the last application, much less take the time to write down its architectural details.

Don't treat documentation as a task you'll do "later." You aren't done until the application is documented, both at a high level and for each module.

"Documentation should be a continuous process, just like testing," says Arseni Mourzenko, a developer at Finaxys, a software consulting company. "[If you] spend a week simply coding a few thousand lines of code, getting back to tests and documentation is very, very painful." Waiting until the last minute tends to yield documentation that looks like the college paper you wrote the night before it was due.

One way to avoid such messes is for developers with ownership of a specific module of code to give a presentation to the entire team explaining how the code works. The process of preparing the presentation helps the developers organize their thoughts and decide what is important to convey. In addition, the presentation style and Q&A challenge the developers' assumptions, encouraging the explanations to be added to the documentation.

What's your security IQ? Take this quiz and find out!

Approach systematic code documentation reviews as you do other parts of the development process. To pick on a small item, everyone needs an editor to catch typos. You depend on your teammates to help you find bugs before they reach production; you should expect other people to give you feedback about whether your comments help them understand how to use the API you wrote.

In doing so, follow all the other rules of doing code review well, such as giving positive feedback before offering criticism.

Ben Kamens, a founder of online education site Khan Academy, makes several good points about code review that can also be applied to code documentation, such as the importance of reviewing in a timely manner. Kamens writes, "Waiting a month to look at somebody's code and then lobbing a bomb of critiques their way is a great way to really piss someone off. Besides being kinda stupid from a technical standpoint, since the code has probably been accumulating users for the past month, this guarantees that the dev will have forgotten a lot of their work, and you'll catch them on their heels. It takes team-wide discipline to review in a timely manner, but it's crucial."

Who, what, where, why, how

Comments and other documentation serve to help other programmers (and oneself, six months later) with clear explanations about the application's design, both at a high level (such as the software's purpose) and in detail (close to the code).

Comments say who, what, where, why, and, in the case of obscure code, how. Indeed, Jef Raskin, the Macintosh's first developer, once argued that comments are more important than code. Why? Because, he wrote, only you can explain "why the program is being written, and the rationale for choosing this or that method."

This doesn't mean you need to annotate and document everything. A lot of programs are made up of glue code that calls library functions. No comments are necessary for these.

Jeff Atwood, co-founder of Stack Overflow, wisely notes, "Strive to make your code as simple as possible to understand without relying on comments as a crutch. Only at the point where the code cannot be made easier to understand should you begin to add comments."

Yes, many programming languages are expressive enough that the code can speak for itself—up to a point. Self-documenting code can only take you so far. Sometimes, a "why" comment is necessary. Your goal should be to save time for the developers who follow you, so include information that keeps them from making the same mistakes you did. A comment that explains why you chose one algorithm instead of another or the reasoning behind an API choice keeps the next developer from having to think through everything you already know.

The code that's crystal clear to you may be mud to a new developer. And just because it's obvious to you today as you write the code, in two years you won't remember what you were doing.

Examples are vital. A single example can save a beginner hours of frustration. Examples also show exactly what you had in mind when you wrote a function, if you demonstrate how you envisioned it being used. For more advanced documentation, such as manuals, you should also use screenshots. An image may not always be worth a thousand words, but it can help.

Know your audience

There are several types of technical documentation. Here I'm focusing on the comments that accompany code and projects in general. I'm still thinking about the beer truck lumbering toward your most productive contributors, and the information you hope they leave behind. But much of this advice applies equally to step-by-step tutorials, project overviews, topical guides, and low-level, deep-dive reference material.

Start by identifying the person who is likely to read the documentation. Are you writing for fellow programmers who know as much as you do about container architecture or IoT security? Entry-level developers? End users? Adapt your writing to meet their needs and interests.

Technical writing expert David McMurrey points out, "For most technical writers, [knowing your audience] is the most important consideration in planning, writing, and reviewing a document."

There are more subtle audience distinctions, too, such as cultural references. Some humor is a good thing. A well-timed quip can make otherwise mind-numbingly dull API documentation amusing, but a little goes a long way. For example, Python documentation is riddled with Monty Python references, says Rich Bowen, Red Hat's community liaison for the RDO project and a longtime documentation writer. The documentation is good, but "not all of your audience consists of young, white, English-speaking men who grew up watching Monty Python," he adds.

Inside jokes can help build a sense of community if you get the joke. If you don't, Bowen notes, "inside jokes point out starkly that you're not on the inside. Tread carefully here. Consider including a reference guide that explains the jokes, and, in the case of dead parrots, points to a YouTube video."

Be clear about the starting point, including assumptions about what your readers know. A great example of documentation that sticks to just the needed facts is the Apache Web Server Getting Started document, which covers what someone should know before embarking on the project.

"Its goal is to draw a line saying what is outside of the scope of the documentation, while also pointing people to resources that do in fact cover those things in great depth," Bowen says. "The HTTP specification, the inner workings of DNS, and content matters (such as HTML and CSS) are firmly outside of the scope of the documentation, but everyone using the Apache Web Server needs to know these things."

It's OK to automate documentation—to a point

Developers always want tools to do the work for them, and they like to automate the parts they find boring or troublesome. As a result, automation tools are appealing, both because it's convenient to use software to summarize what a block of code is doing and because those summaries can stay up to date even when the software is refactored.

No magic program lets you wave a wand over your code to give it great documentation. But there are tools that can give your comments and documentation a running start. Three of the most well-regarded are Doxygen, Sphinx, and GhostDoc, a Visual Studio extension.

Keep in mind garbage in, garbage out applies to documentation as well as code. If your code isn't clean, no tool is going to make sense of it for you. You must refactor your code before using documentation automation tools.

Take human language into account as well. Many programmers, especially those for whom English is a second language, have trouble writing good documentation even with the best intentions. In these cases, you need to hire documentation writers.

Once your code is properly annotated, other tools can help you create user-friendly documentation. The easiest way to do that is with a wiki, advises high-performance computing engineer Ben Cotton, though they're not well-suited to offline editing or for republishing in other formats. "Keeping the content organized such that it can be found easily can be challenging," Cotton says. "Unorganized wikis are particularly prone to duplicated and stale content." 

Another option is rendered documents. You write the content in your favorite text editor and then turn it into a publishable document with another program. While you can still do that the way they did in the stone axes and bear skin days of vi and LaTeX, modern tools include Publican Markdown; reStructured Text, which is often used with Sphinx.

Even if you follow these steps, you may still face an uphill battle getting people to annotate their code properly and produce good documentation. But you'll be a lot better off than when you started.

Code documentation: Lessons for leaders

  • Good comments don't restate what the code does. They give it context and share why decisions were made.
  • Treat internal documentation as secret messages you leave for the next developer (who may be you).
  • Documentation is an important part of the development process, not an irrelevant add-on. Treat it with the respect you show for every other part of the software lifecycle.

This article/content was written by the individual writer identified and does not necessarily reflect the view of Hewlett Packard Enterprise Company.