root / PyCon07 / material / seven_laws.txt

The seven laws
==============

.. contents:: The seven *laws* for technical writing:

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

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

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

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

|important| Spending too much time to find something in the documentation is 
a bad sign.

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

|important| Never write a document that doesn't have a template


.. |important| image:: important.png