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
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)
- Use short sentences and simple writing style.
- Use simple vocabulary
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.
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
Drop the foo and bar habits. Examples must be real-life examples, and usable as-is.
>>> foo = graph.calculateSquare(1, 1, 1, 1) >>> bar = graph.renderSquare(foo)
>>> square = graph.calculateSquare(1, 7, 1, 10) >>> square_view = graph.renderSquare(square)
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.
Use a clear document portfolio to facilitate the reading. Document
- 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