What’s the Value of Software Documentation?

There was an interesting debate on the Stack Overflow podcast regarding the value of software documentation. On one hand, organizations always think they need more of it. On the other hand, programmers typically hate writing it and usually think it’s worthless.

Who’s right?

The Problems with Docs

The real problems with software documentation for large internal applications is threefold:

• Small Audience: You may write the most beautifully detailed document in the world, but odds are it will only be skimmed and never actually read. As we all know from Steve Jobs famous quote “No one reads anymore”.  If people don’t read normal books by popular authors, are they really going to read your dry 20-page detailed software doc?
• Already Obsolete: When programmers start new projects, they typically don’t read the documents because they assume they are obsolete, and most of the time they’re correct. By the time the massive doc is finished, the software has often already changed by 20% and the screenshots need to redone.
• Great Programmer != Great Writer: Great programming and great writing do not necessarily go hand in hand. In fact, some people get into programming so that don’t have to communicate with anything other than a compiler. There’s nothing wrong with that, but don’t expect your programmer to write the clearest software documentation.

So, given that we’re up against all of this, is there any hope for software documentation?

The Bare Minimum

There are some types of documentation that add real value to a project. Let me list those and then talk about style:

• Scope Doc: In some form, you need to document what you’re going to build. Now, I’m not advocating a 200-page waterfall-style spec doc. But I’m saying that everyone has to be on the same page with what is being built and a scope doc is the best way to do that. Mockups using something like balsamiq are a nice touch in a scope doc as well. Spolsky has the canonical post on writing scope docs.
• Install Guide: The install guide has two functions: 1) It tells new developers what they need to install to get the project running, and begin development on it 2) It also helps the IT staff know how to rebuild the app if the server dies. This doc would typically include items like location of source control code and third party apps to install.
• User Guide Inline Help: Instead of a user guide that no one will read, implement some sort of inline help in your software application that appears right where the user needs it and helps them understand their specific problem.

For each of these docs, they need to be light: 5 pages or less, and heavy on bullet points, images and sub headings. The bottom line is that people don’t read anymore; they skim and software docs need to accommodate this fact.

Rule 1 of writing software for nontechnical users is this: if they have to read documentation to use it you designed it wrong.  

–Eric S. Raymond