Writing Documentation: Teach, Don't Tell

Programmer Steve Losh has written a lengthy explanation of what separates good documentation from bad, and how to go about planning and writing documentation that will actually help people. His overarching point is that documentation should be used to teach, not to dump excessive amounts of unstructured information onto a user. Losh takes many of the common documentation tropes — "read the source," "look at the tests," "read the docstrings" — and makes analogies with learning everyday skills to show how silly they can be. "This is your driving teacher, Ms. Smith. ... If you have any questions about a part of the car while you’re driving, you can ask her and she’ll tell you all about that piece. Here are the keys, good luck!" He has a similar opinion of API strings: "API documentation is like the user’s manual of a car. When something goes wrong and you need to replace a tire it’s a godsend. But if you’re learning to drive it’s not going to help you because people don’t learn by reading alphabetized lists of disconnected information." Losh's advice for wikis is simple and straightforward: "They are bad and terrible. Do not use them."

Comments

Re:Source code

[Entropius]

Do you really want to read the source code for ssh every time you forget whether it's -p or -P to specify the port? (It's one for ssh and another for rsync...)

The web and hyper text are a challenge

[EMB Numbers]

As an author of three successful dead-tree programming books, I have a few observations.

1) I use the electronic versions myself because of easy search (better than an index) and copy/paste.
2) In book format, it's possible to lead a reader through topics in a sensible order that builds on prior topics.
3) The challenge with electronic/on-line documentation is that there is no expectation that readers will approach the material in any particular order. Readers type a search term into google and up pops a page or two of documentation. How can the author make safe assumptions about the definitions of terms and prior conceptual knowledge the reader will have? Adding links to the definitions of terms and links to chapter oriented conceptual documentation doesn't usually help because readers are impatient, and there is no good place in the middle of the documentation to start.
4) Many readers don't know the terms to type into google and therefore aren't lead to the relevant conceptual documentation even if they would have read it had they known.

Re:Stack Overflow

[PRMan]

Um, that's why people VOTE on the correct answer. One of the top 2 answers is virtually ALWAYS the correct answer (usually 2 ways of solving the same problem that you can choose from).

Re:Docs vs tutorial

[lgw]

WHile the difference between a textbook and a reference manual should be obvious to all, TFA still has a point: good documentation should include both.

Most docstrings I see are worthless: they add nothing to the code right below them. OTOH, a bit of tutorial-style documentation with examples can be golden. Often that makes well-written unit tests the best docs, or at the very least, if you're going to provide examples, they should also be unit tests - another test is always nice, plus you know your examples actually work.

Re:Um, no

[murdocj]

No. An expert may be an expert in an area, but until he's familiar with your code, he's not an expert in your system. I've spent way to much time deciphering code where a single sentence explaining what the hell the code was doing would have saved time. If you had enough time to write the system, you have enough time to document it. And if it's hard to document, that's a hint that it's a crappy system.

Re:Docs vs tutorial

[dgatwood]

There's a difference between a tutorial and documentation? Who'd have thunk!

Actually, no there isn't. A tutorial is one type of documentation. Tutorials are documentation for processes. Non-process subjects require other approaches. It is important to write the right types of documentation based on the likely audience and the subject matter.

I disagree with many things in this article, not because the points are invalid, but because they conflate misuse of tools with low quality of tools. For example:

Wikis are great tools for writing documentation. They make it easy for people to fix minor errors when they notice them. They make it easy to collaborate on documentation without having to deal with the relatively high overhead of source code version control systems (which are particularly awful when merging structured content like XML and HTML).

What the author is complaining about is not the wiki, but rather the fact that those projects have no one who is responsible for maintaining the documentation. If no one is responsible for writing the docs and ensuring their completeness, the documentation will inevitably be half-finished, whether they use a wiki or some other mechanism. The wiki is not an alternative to writing documentation, but rather is a tool for creating documentation.

Doc generation software is great for writing reference documentation. By placing the content into the source code, it becomes the responsibility of the programmer to update any behavior changes when they modify the behavior of a function. It also means that the documentation for the function is easily readable right there in the source code when you're trying to understand a function. By producing the generated documentation, you then have a convenient reference for all your functions, methods, classes, data types, etc. that is readily searchable, indexable, and (perhaps most importantly) is viewed in a separate app or window from your source code so it doesn't force you out of your coding flow when you need to look something up.

Once again, what the author is complaining about is not the doc generation tool, but rather the fact that those projects have no one who is responsible for writing the documentation. When used properly, the output of doc generation tools is every bit as good as documentation produced by hand. However, it takes exactly as long to write that documentation in the source code as it does to write it in a word processor. It is not a tool for saving time, but rather a tool to aid in maintaining consistency between behavior and documentation.

To do software-generated documentation correctly, you need to add comments that explain every field in every data structure, every class, every function or method, and for particularly complex functions, even documentation for many of the local variables. You should write code in your build system to warn about undocumented methods and data structure fields. For example, in one project I regularly work on, there are almost 17,000 lines of documentation comments out of just shy of 59,000 total lines of code—a whopping 28.8% of the total code volume. The result is that it is fairly easy to learn what each piece does in the context of the code while you're looking at it, and the automatically generated documentation is pretty thoroughly fleshed out reference documentation for the project. One particularly complex class by itself produces a whopping 72 pages of reference documentation.

The problem that folks run into is that they usually don't put in any doc comments at all, or at best don't actually take the time to write the thorough comments that are needed to make the output from automatic reference documentation tools be useful. As a result, when you build the reference docs, you end up with an empty skeleton that isn't of much value at all. This is not a flaw in the tool; it is a flaw in the development team. They didn't take the time to write the documentation.

And so on.

Re:Source code

[smash]

Given the number of bugs in most code, I'd suggest that it is pretty poor documentation for what the code is SUPPOSED to do.