There’s only a few days remaining before tutorial cancellation at Pycon, if you have interest in some of them, it’s time to register !

I have completed my outline for the tutorial I’ll be giving. If you consider to attend, you should bring your laptop and have this elements installed on it, to maximize your pleasure :

• Python 2.4 or 2.5
• docutils
• setuptools
• pylint
• cheesecake
• subversion, client and server (optional)

(PyCommunity will be provided at tutorial day).

Updated outline:

- writing a document

  - mastering reStructuredText
    - presentation of reStructuredText
    - distribution of cheatsheet
    - exercises

  - writing techniques and tips
    - presentation of the ten laws, with examples
    - exercise in binomial

  - team writing
    - presentation: bad writer, good designer VS good writer, bad designer
    - exercise: doc review

- writing documents in Python

  - documenting a module
    - presentation : which module to document, how to split content into docs ?
    - exercise (on an existing package)

  - documenting a package
    - presentation: README.txt and friends
    - exercise: writing the minimum files, testing with cheesecake

- using documents for test-driven developement

  - mastering doctests

    - presentation: unittests ain't doctests
    - exercise: spliting tests between doctests and unittests

  - continuous documentation
    - presentation: designing through doctests
    - exercise: creating a module with its doctest

BREAK

- writing documents in a Python Project

  - writing tutorials
    - presentation: what's a tutorial
    - presentation: how to write a tutorial
    - exercice: write a mini-tutorial

  - writing cookbook and recipes
    - presentation: what's a cookbook
    - presentation: how to write a recipe

    - exercice: write a recipe

  - writing a project glossary
    - exercise: write a glossary

  - crosslinking everything
    - exercice: link the recipe, tutorial and glossary

- website autogeneration with pycommunity   

  - presentation: pycommunity
  - exercise: setting up a subversion structure
  - exercise: setting up a hook for website autogeneration
  - customize pycommunity for an existing website

- conclusions

I have updated a bit the PyCon Wiki tonite :

• A more detailed class outline about my tutorial on documenting
• A BoF about creating a content repository standard in Python

I’ve been reading Carlos’ post about Zope 3, and his thaugths on the role of the framework.

I want to react on this and give my opinion on Zope future and on Python Web developement as well, because I feel that people are not debating on the right thing.

Since a few months, a lot of people in Zope community are seeing Zope 3 as packages that can be used in Zope 2 or elsewhere. This is probably true. A lot of people are also using CherryPy, Django, TurboGears, .., and dropping Zope for some reasons. These reasons are probably right. (my reason to drop Zope would be the ZODB).

But beside this reasons, (every framework has pro’s and con’s) there’s a missing brick in the Python Web Developement ecosystem that exists in Java world: a standard for document repositories. It’s called JCR or JSR-170. Some people in Zope community have talked about it in the past. Nuxeo did a bind as well with nuxeo.jcr, then dropped Zope/Python for Java (which is totally logical given where CPS software is heading).

I strongly believe that the future and the maturity of all Python web frameworks relies at the first place on a common document repository standard, like DB API did with SQL.

Python web developers, it’s time for all of us to cooperate and create such a standard in Python, and an implementation based on SQLAlchemy. This would let Zope drop the ZODB (yepee) and let every web developer use the best of all frameworks (the Zope Component Architecture, the Django approach, etc.) since they would all be able to work with a given repository.

I would like to see the PSF and all framework core developers support such a project.

edit: oups.. I just realized I have used a french acronym in the title (SGBD). The english one is RDBMS 

Test-Driven Development is widely used in the Python community to create quality software. The benefits of such approach is not to be proved anymore. It creates better software by :

• preventing regression
• making the developers actually think about what they write
• providing a real help for newcomers : unit and functional tests are showing how the code was made and how it has to be used.
• …

Python has brought a real enhancement to test-driven developement with doctests. They allow developer to write documentation with embed code examples that can be run for real. This allows a team to integrate documentation in the development cycle and to replace most of their tests with documents that are always up to date: documents become tests.

In the meantime, documentation has always been the black beast of developers. They hate writing it and most of the time, a software project website is never up to date if there’s no one dedicated to this task. For open source projects, the website is the most important media and should always reflect to what is happening in the code base.

doctests can resolve this problem by automating documentation creation at all level

I have used this principle to create a Document-Driven Developpement (DDD) approach, which provides to a project team a way to automate the update the project website : each commit on the code base calls a script that generates on the fly html pages for:

• the api
• the glossary for the project
• documents for all important modules
• tutorials
• recipes
• …

This method will be fully explained at my PyCon Tutorial (February, 22th).

I will published by then the script that automates the creation of the website, using a subversion repository that follows a few guidelines (in its content and structure).

Can’t wait to be there !