The seven rules of technical writing

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...