I have sent a proposal for a tutorial at Pycon, covering the way to
document a project through the developement cycle. It's based on Agile
Documentation principles and provide a way to smoothly integrate
documentation in the daily developer work.
Here it is:
Documentation plays a vital role in open sources projects.
Well designed, it attracts new people into the project,
help the users use it, and raises the quality
of the code base and the team work.
In other words, it builds the shared knowledge.
This tutorial is based on a talk i've made
at Europython about zope-cookbook.org, and go
further by giving a complete set of practical methods
that can help a team to create and maintain an up to date
documentation with no pain.
An example code base will be provided and used for all
By the end of the tutorial, people should be able to
integrate documentation in their developement process,
the same way they probably did one day with unit testing.
- agile documentation principle (short overview) - mastering doctests (overview + exercises) - mastering reStructuredText (overview + exercises) - writing techniques and tips (examples + exercises) - shapes of documents (overview) - building document templates (examples + exercises) - setting up documentation writing in the development cycle: - continuous documentation (examples + exercises) - team writing (exercises) - portfolio (overview) - setting up a help center (overview + exercise) - linking it all together (complete example (svn/trac/website/etc..))
* Intended audience
All, except the doctests exercises that will have a bit of coding
the zope-cookbook talk:
Now let's wait and see if it's accepted :)
"Pycon" "Agile Documentation" http://indico.cern.ch/contributionDisplay.py?contribId=5&sessionId=53&confId=44