I am here at PyCon, enjoying the talks. I will blog about what I have seen in a few days. Until then, let me drop here the seven laws on how to write good technical documents.
These laws are the rules I have synthetized for the tutorial I gave yesterday, and that can be followed by anyone who write for softwares.
They are based on advices taken from:
- Writing With Power (Peter Elbow)
- Agile Documentation (Andreas Rüping)
- My own experience on the topic.
The seven laws for technical writing:
- The Two-step writing process
- Simple style
- Targeted readership
- Focused information
- Realistic examples
- "Light but sufficient" approach
- Structured documents
The Two-step writing process
Writing should be done in two stages (Elbow, 1980):
- a free writing where ideas are written on the paper no matter the
shape.
- a review stage where things are structured and reviewed.
Each stage should take 50% of the time.
-> Split you writing time in two phases, no one can write it right the first time (except Mozart)
Simple style
- Use short sentences and simple writing style.
- Use simple vocabulary
Targeted readership
Focus on your target when you write a document (Rüping, 2003).
Assume their background knowledge to restrict the scope of the documentation.
-> A prerequest section can help a lot.
Focused information
A document is about a clear focus.
A precise title for each section and the document itself, and a summary can help.
-> If you cannot easily name the document or one of its section, there's a problem
Realistic examples
Drop the foo and bar habits. Examples must be real-life examples, and usable as-is.
Neh:
import graph
>>> foo = graph.calculateSquare(1, 1, 1, 1)
>>> bar = graph.renderSquare(foo)
Better:
import graph
>>> square = graph.calculateSquare(1, 7, 1, 10)
>>> square_view = graph.renderSquare(square)
"Light but sufficient" approach
A working software is more important than the best documentation in the world (Ambler, 2002).
Quality over Quantity is the best rule.
-> Spending too much time to find something in the documentation is a bad sign.
-> Think documents like code. Always limit the size of sections, examples, etc. Modularized documentation is the key.
Structured documents
Use a clear document portfolio to facilitate the reading. Document
should use:
- an abstract with a readers guideline
- a toc when there are more than one section
- references
- glossary
- tables and diagrams
-> Never write a document that doesn't have a template