I hate writing documentation, but I have to. Good actual documentation significantly decreases efforts for introduction new teammates. And of course, nobody would use perfect open source code without documentation. So I have written plenty of documents. The most of them are miserable. But I tried to find a way to make them better. And it seems, I have found the general mistake I did.

Typical documentation consists of three parts:

• Getting started guide describes main features and principles.
• Advanced usage guide describes each feature in details.
• Internals or API documentation describes low level things, i.e. particular modules, classes, and functions. It is usually generated from doc-strings of the sources.

I used to write documentation in the direct order: getting started tutorial, advanced section, and finally internals. Don’t do that. If you want to write good documentation, you have to write it in the opposite order.

This is how it works. The most important thing of any documentation is cross-linking. When you describe a feature that consists of a number of smaller ones, you have to link each mention of the smaller feature to its full description. That is why internal documentation generated from doc-strings is your foundation. It is quite easy to document particular function or class (lazy developers guess it is enough). So when you describe how the things work together, you can link mentions of the particular thing to its own documentation, instead of overburden the entire description by the details. The same works for getting started tutorial. It must be concise, but there must be links to the full description of each feature it mentions.

There is no magic. This technique just makes documentation writing process more productive and fun. Use it and make your documents better and your users happier.