8 rules for documenting your product

This year I’ve had some really frustrating experience working with several new libraries and tools. In most cases, the reason for the frustration was related to the abysmal quality of the documentation for the products I've used. I do not want to point fingers and name the companies – from what I’ve seen, the problems I’ve encountered are not specific to these particular vendors, but, rather, plague the whole industry. Instead, I’ve tried to summarize my experience into some do’s and don’ts. So, if you want the user to have a good time working with your product…

1. Provide documentation in a well-known format. Make sure users can easily print all documentation, or selected parts. Avoid custom help browsers, exotic file formats and all this kind of garbage.
2. Provide all types of documents. Generally, a good set of documents should include Setup Guide, Manual, Reference and Examples. Each document here has its own purpose, and cannot be replaced with another. For some reason in many cases I’ve seen API reference provided as both Reference and Manual documents. Don’t do it. In the best case, user spends extra time trying to understand from the reference the right way to do something. In the worst, user has no other choice but to use Google.
3. Do not “crowdsource” your documentation. Forums, wikis, mailing lists, FAQs are wonderful, very useful tools – but they can’t replace a normal, “static” documentation.
4. Document all the relevant concepts. If the product introduces a new concept (algorithm, data structure etc.), it definitely should be described and explained as thorough as possible. If the concept is not new and is already used at least in some part of an industry, a reference should be placed to the available description and explanation. (Of course, a good judgment should be applied here. Definitely, there is no need to explain the idea of, say, mouse cursor. ) Specify all differences of your product with the existing standards.
5. Provide a 100% complete API reference. Even the trivial calls, like getters and setters should have descriptions. There reason for this rule is quite simple: it’s much easier to just document everything, than to try and correctly divide methods into trivial and non-trivial. Besides, pretty often a seemingly trivial method turns out to be much more complex than you initially thought.
6. Give each user access to all documentation. I’ve seen some companies allowing users to access only documentation for the products they purchased, and in my point of view it is absolutely ridiculous.
7. With each new release provide a “What’s new in this release” document, or at least a changelog. The document should not only highlight new features, but also specify most prominent bug fixes, and tell user about all cases when the new release is not backwards-compatible with the previous one.
8. Constantly maintain all dynamic online resources. Forum should be moderated and questions posed there should be answered, some popular questions should be added to FAQ, wiki should be cleaned etc.

Technorati tags: software, programming