My tutorial proposal on how to document a Python project, has been
accepted. I have quite a good idea on the things I need to present for
people to understand how to integrate documentation writing in their
development cycle.See the class outline for a summary
The main idea behind this tutorial is to explain how documenting can be
done through coding and testing, in order to create lightweight but
sufficient documentation instead of creating documents at the end of the
The technique is based on:
- literate programming, introduced by the father of Tex, [Donald Knuth] - Agile documentation principles, which uses agile techniques for document writing . These have been [summarized in a book by Andreas Rüping].
and provide simple processes to avoid the "programmers hate writing
For open source projects, the final step of agile documentation is:
- to automate the update of the dedicated website everytime developers change the base code. - to provide a visible document landscape to anyone interested to the project - to increase the quality of the code base - to make developers become good writers, and make them love it
This tutorial is based on my work on zope-cookbook.org, which tried
to follow a fast-moving technology : Zope, and some work on several
Python open source projects, books and articles I have written.
Nevertheless, the conference is next February, and I would like to
integrate more feedback on how people feel about documenting their
If you are a developer, using Python or any language out there, or a
project leader, I would love to get a few words about your experience on
the topic, in order to enhance this tutorial.
- What is the place of documentation in your project cycles ? - What are the different document types you use ? - What kind of formats do you use for you document ? (Word, OpenOffice, Latex, reST..) - Do you have dedicated people that write documentation ? - How do your developers feel about documentation ? - ...
Please don't hesitate to comment this entry, or to senf me an email (ziade dot tarek at gmail dot com)
"Pycon Tutoria" "Outiline" "Literate programming" "Donald Knuth" "Agile documentation" "http://zope-cookbook.org/"