Write a good documentation — please!
I read a lot of documentations in my day job. Most times I find myself lost in those documentation and have to re-read them multiple times.
Recently I realized the reason I can’t follow them carefully is not because they are technically challenging, but because they are structurally confusing!
So I put a short doc together summarizing resources I rely on for writing effective documentations.
What kind of documentation are you writing?
There are 4 major kinds of documentation with their own distinct purposes. Structuring documentation according to its purposes helps ensure that they serve their function adequately, your reader can follow it, and makes it far easier to maintain it.
- Tutorials: Learning-oriented (learning how to do something)
- How To Guides: Goal-oriented (Solving problems that your reader has)
- Reference Materials: Information-oriented (cheat sheets)
- Discussions/Explanations: understanding-oriented
The key to successful documentation (easier for the author to maintain and for the reader to use) is to keep them separate based on their type (more info on those 4 types at the end of this post).
Action: Explicitly structure your document based on their type.
Common traps: How tos and tutorials are often conflated. The mashed up version doesn’t do a good job either as a how to guide or a tutorial.
Maintain your documentation
there is no documentation that can be printed and never revised. Technology is constantly changing, and the most used systems are the most updated. Therefore, the most important documentation is the one that gets outdated faster.
Action: Separate the how from the why. How to use the system changes constantly, but why the system exists is a much more stable concept.
Don’t neglect prerequisite knowledge
Take extra care to fill in or at least link to prerequisite knowledge. Even an action as small as pasting credentials or other documentation you used can save hours of future searching.
Action: Ask somebody who is distant to your project to re-read your document and fill in any blanks.
What is a Tutorial?
They are a set of concrete actions, built around a particular and explicit intended outcome.
In tutorials, you are responsible to take your reader by hand, step by step through a series of concrete actions to successfully get them to your intended result.
What is a How to Guide?
Direction to solve a specific problem/end.
How guides don’t explain, but have clear steps that can be followed by readers to get to a clear and specific goal. They can assume basic knowledge of the reader.
Those steps should work every time, for as many users as possible.
What is a Reference Material?
Technical descriptions of the machinery and their operation. They only have one job — to describe!
They list things that exist. Their structure should mirror the architecture of the domain itself so the user can navigate the code and the reference material at the same time.
What is a Discussion/Explanation?
They explain why things work as they do! They offer a perspective, and help the user understand the subject and make connections.
