Two Wrongs

(don't make a right)

Documentation: Reference Manual vs. Cookbook

by ~kqr

Documentation for software and programming languages tends to use one of two styles. The probably most common style is where it resembles a reference manual. It clearly states, in a list-like fashion, exactly what things exist – preferably with an easy way to cross-reference, such as with hyperlinks.

At the extreme end of that, you have, among other things, some Haskell libraries. It just states what everything is, and you are supposed to use other resources to figure out how to use it. But you can click almost everything and be taken to its definition. If that's not enough, you can click the "Source" link and be taken to the source code for it.

On the other end of the scale, you have something like the Nginx docs, which consist mainly of a few examples, extremely few hyperlinks and nothing more than that.

Both approaches are valid, and suitable for different circumstances. When people are exposed to one of the two extreme ends, they tend to call for the other. While it's probably obvious when viewing both extremes side-by-side, it tends to be forgotten at times: the ideal documentation probably contains a fair share of both reference manual-style material and a bunch of examples with the most common use cases.

If you are bad at writing examples, it is probably a good idea to brush up on those skills now. If you are bad at cross-referencing, you should practise that.

If you enjoyed this article, you might like others tagged with