Here are the slides I have made for the PyCon tutorial:

• S5: http://programmation-python.org/pycommunity/pycon/PyCon07/slides.html
• reST: http://programmation-python.org/pycommunity/pycon/PyCon07/slides.txt

Don’t hesitate to send me feedback about them

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

I’ve been working a lot on PyCommunity packaging lately, so it can be ready for my PyCon tutorial. Version 0.1 will be released by then and will autogenerate html pages for a Python project that bases its documentation on reST files.

There are a few mandatory files that have to be present in the project for the tool to work, but it is not really restrictive. I tried a few runs on Zope codebase and it works fine, besides a few problems with epydoc (some Zope files are breaking epydoc, I need to dig on this) and a few failures on some malformed reST files.

PyCommunity is based on Cheetah templates, that can be customized to smoothly integrate generated pages into an existing website.

Features to complete for 0.1:

• Cheesecake index report for each package
• test coverage report for each package, using trace2html
• Crunchy frog integration
• Pygments integration
• SVN hook dameon with a queue, so the generation can be done smoothly
• Folder and file skipping to avoid the process of unwanted content

The source code is in a Mercurial repository, right here: http://hg.programmation-python.org/repositories/public

If you follow this link, you will see a generated site based on a fake project used in PyCommunity unit tests.

As a young PUG, we’ve missed the deadline last year. We’re in this year !

The AFPY (Association Francophone Python) organizes this year, at the annual FOSDEM conference (24/25 February, Brussels, Belgium) a Python Developer Room.

The room schedule can be followed here: http://www.fosdem.org/2007/schedule/devroom/python

A lot of interesting Python-related conferences (and Zope as well) will take place, and a few sprints will probably be organized as well.

So if you are in Europe, not attending to PyCon, the FOSDEM is the place to go to !