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:

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.

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)

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