Writing good documentation
Created: February 23, 2020 / Updated: November 2, 2024 / Status: finished / 2 min read (~213 words)
What do you need to know to write good documentation?
You need to know who your audience is. You need to know what they should know so that you can make assumptions about their knowledge. You should also be able to tell what they won't know. It is mainly this lack of knowledge that you need to fill when you write your documentation.
Once you have established who your audience is, you should state it clearly. This way, readers will be able to determine if they identify or not with the target audience, which can help them better frame how to read the documentation.
The purpose of documentation should be clear. Is it to describe a specific use case, provide a getting started guide, answer specific questions regarding functionalities?
You need to state explicitly what you will cover and not cover in the documentation. Readers may start reading your document which contains assumptions about their knowledge, but if they do not have this knowledge, they should know where to acquire it.
It should be easy for readers to know where to reach the author of the documentation or people knowledgeable enough to guide them to the right people.