Writing good documentation is easier in many aspects than writing code, but many developers think otherwise. It will become easy once you start following a simple set of rules regarding technical writing.
We are not talking here about writing a novel or poems, but a comprehensive piece of text that can be used to understand software design, an API, or anything that makes up the code base.
Every developer can produce such material, and this section provides the following 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...