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 project.
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 document" effect.
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 application.
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)