We came across this article by Jacob Kaplan-Moss titled “What to write“. The article shares some great tips on writing great technical documentation. We’ve reproduced some parts of the article and summarized some main points below which we think would be the most useful for Mashapers.
Formats of a technical documentation
A well-documented project needs to provide many different forms of documentation. At a high level, you can break down the different types of technical documentation you need to provide into three different formats:
- Step-by-step tutorials,
- Overviews and topical guides to the various conceptual areas of your project, and
- Low-level, deep-dive reference material.
Good tutorials are a must as they’re usually the first thing someone sees when trying out a new piece of technology. A good tutorial should:
- Be quick. A new user should be able to experience success within thirty minutes.
- Be easy. Play-test the tutorial under all sorts of different circumstances, making sure that it always works so that the user can and will experience success at the end.
- But not too easy. For users who are not qualified to use your project, they should fail quickly. Don’t get them through the tutorial only to run into a wall later on.
- Not gloss over bad choices in the interest of expediency
- Demonstrate how your project “feels” in the short and long term. Show off different areas of the project, and make the tutorial cross-sectional.
In the tutorial, the slope of the learning curve can be more gradual than later tasks. However, it should not be so easy so that things suddenly get much much harder after the tutorial is finished.
Topical guides is the meat of the technical documentation as the user needs to dive into details of specific areas after they have learnt the high-level concepts from the tutorial.
The main goal for topic coverage should be comprehensiveness, with the reader coming away feeling that they know the majority of the possible options, and more importantly, how all the concepts fit together.
It needs to take a deep dive into specific areas, but does not need to cover every single configuration option or function argument (leave that for reference materials).
The reference material should contain all the public APIs your project provides. These should be designed for those who already know how to use some API, but need to look up the exact arguments some function takes, or how a particular setting influences behavior, etc. Reference materials are not substitutes for good tutorials and guides which provide high-level overviews. The reader needs to first know what they are looking for (through tutorials/ guides), before they can look for it (in reference materials). While guides give the “why” in a technical documentation, reference materials should give the “how”.