Writing good documentation is easier in many aspects than writing code. Most developers think it is very hard, but by following a simple set of rules it becomes really easy.
We are not talking here about writing a book of poems but a comprehensive piece of text that can be used to understand a design, an API, or anything that makes up the codebase.
Every developer is able to produce such material, and this section provides seven rules that can be applied in all cases:
Write in two steps: Focus on ideas and then on reviewing and shaping your text.
Target the readership: Who is going to read it?
Use a simple style: Keep it straight and simple. Use good grammar.
Limit the scope of the information: Introduce one concept at a time.
Use realistic code examples: "Foos" and "bars" should be avoided.
Use a light but sufficient approach: You are not writing a book!
Use templates: Help the readers to get habits.
These rules are mostly inspired and adapted from Agile Documentation...