Five Principles to Good Documentation Writing (Good Documentation Series)

The last time you guys heard from me, I was griping about the lack of good documentation out there. So in an effort not to be that guy who complains about stuff all the time, here are my tips for writing good documentation.

Five Principles

1) Know the documentation’s purpose (and audience). Is it going to be used by developers? Is it for QA folks to know the process by which to test something? Is it just a quick-reference of commonly used shortcuts? Is it a basic introduction to the concepts behind the software? Is it the end-all-be-all source of knowledge for it? Whatever the case, knowing the audience you’re writing for and why they’re reading it will take you a long ways toward making relevant docs.

2) Lay out how data flows through the software (diagrams are handy here). Think “Step A retrieves data from an endpoint, which causes step B to parse the data and then return it so that step C can do X with it.” In other words, spill its guts all over the place. This’ll help those who want to delve deeper into the application to do so, and also makes it easier to build on top of it. Not to mention that debugging becomes easier when things are laid out clearly and simply (one might even make a good argument that clearly == simply). When you know how data flows through the application, finding the clogs is a cinch.

3) Provide lots of code examples. Often when learning, there is no better way to figure something out than by seeing it in action. That said, don’t make the mistake of just providing examples as your documentation. This leaves readers scratching their heads with questions like “what does this actually DO?” You might have a usage example, but unless one can deduce a lot of information from that usage example, the documentation will be very limited in its effectiveness — users should not have to look at your source code to figure out how things work.

4) Document the project on multiple levels. Personally, I like when there are three tiers of documentation: a high-level overview, a mid-level instructional level that will answer about 70% of the questions I might have, and a nitty-gritty detailed blueprint of the system. Organizing documentation like this gives readers a quick way to find anything they’re looking for. Cutting down search times will win you friends (and influence people).

5) Take notes while you develop. This will drastically cut down on the time it takes to create documentation. It doesn’t take long to type a couple lines on how something works as you’re writing it. Not only does it help with creating the documentation, but it can also help you identify flaws in logic or over-complications in the design of the software.

On Tiered Documentation

Your high-level overview should give readers an idea of what the product is capable of. It should get them thinking about all of the stuff they *could* do with the application. I like Ruby on Rails in this regard. Its Getting Started page railspic is a good example of a high-level overview. It gives you a few commands that will allow you to have a skeleton site up in minutes. It also goes over some of the behind-the-scenes stuff that is going on, but it presents them as optional “more information” sidebars. That way it doesn’t bog you down in technical details. After all, you’re just looking for how to use the stupid thing first, right? Once you can get something functional with it, then you can start exploring the innards of the the framework.

Mid-level documentation should be the meat of your docs. It should provide the average user with most of the things they’ll ever need to know to use your api/library. At this point you’re getting into more of the behind-the-scenes workings of the code. In short, this level of documentation should answer the question “If I were picking this up with no prior-knowledge, is this enough to answer all but the most detailed questions someone might have?”

Low-level documentation is kind of like the open-source of documentation. You’re spilling the beans on exactly how everything works. Again, it all needs to be readable. You don’t want readers to get lost in a muck of techni-speak. A decent example of this is my blog on the SAX parser I wrote in Python. It’s a pretty short script, so I give the entire code. I explain it from the beginning on through, going through why variables are used and when they’re changed. Dan Funk created a great little diagram that helps a lot with the understanding, which he created based off a reading of the documentation. (Disclaimer: While that post is reasonably easy to follow, there are several things I’d like to change about it at some point!) The post begins by telling you the three functions available from the new class, and what they do. Then it gets into the details of how it does those things.

In short, when writing docs with a tiered approach, you should think of whittling the application down bit by bit. This way, you progressively add more detailed information to the reader’s understanding, building on what they already know. The only caveat is that they have to have solid understanding of what you’ve presented to them already, hence the need for clear and concise documentation

One Last Thing

Above all, good documentation should be intuitive, otherwise it’s usefulness is severely diminished. After all, what good is documentation that you can’t find, navigate or understand? If your documentation isn’t doing that, consider revamping it.