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:

Summary

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
exercises.

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.

Presentation outline

• 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:
- http://indico.cern.ch/contributionDisplay.py?contribId=5&sessionId=53&confId=44

Now let’s wait and see if it’s accepted

I have started a few months ago to write a cookbook for Zope 3, both in english and french. The challenge was to be able to:

• follow the project code base wich is evolving (too) fast
• provide transversal knowledge for developers that wants to create real world things with zope

The project was growing and doing well, but I had to stop, because of Nuxeo’s drop of Zope: it became too hard to follow Zope 3 development exclusively in my spare time.

Nevertheless, Baiju copied the recipes in his wiki, and hopefully they will be reinjected in the work done their to construct a mainstream book.

However, this experience was really exciting, because I had to set up a writing process, explained last summer at Europython, based on agile documentation principles, to be able to provide up-to-date materials, and examples codes.

As a souvenir ;), I have generated raw pdfs in both english and french. They might be useful to people that are discovering Zope 3 out there, as they also introduces developing methodologies.

Here they are:

• Zope 3 cookbook in english
• Zope 3 cookbook in french

Let me know of they are useful to you !

Important note: those recipes are not following a book plan, so the pdf table of content can look a bit strange to readers.

Thing changes

For about three years, I had one of the best place a Python developer could dream of in France : one of the most Python-friendly company out there (Nuxeo), that was promoting the language everytime it was possible. In this context, even though you’ve told so, you don’t feel how Python is small compared to Java in the business area. You just don’t want to hear about it because you develop great software, and feel happy with Python.

But time are changing, and when your company decides to drop Python for Java for the main language, a lot of things goes through one developer’s head.

• First of all, I felt like back in college, where people were laughing at me and my redhat box, because everybody was under Windows and thaught Linux was a piece of crap. I felt like I was pushed into some kind of minority. Weird feeling.
• Secondly, I felt a little bitter because I understood, while all arguments of such a switch are quite understandable, that it’s mostly a problem of money, because Python can do what Java does. If I would’ve been a billionnaire 10 years ago, Python would be the standard nowadays, and all arguments could be flipped ;). But the reality is here now, Java is the main stream language in OSS. Java and its related technologies are interesting, but I still look at them like I look at Ruby: what are their strengths ? How Python can learn of them ? This is a pragmatic Pythoneer habit.
• Last but not least, with all the evangelism I’ve been doing these past years, in english or in french through my book or the AFPY user group, I still want to promote Python and be part of its community.

But how ?

This blog will throw ideas about marketing Python

All the talks about my company switch makes me feel like marketing Python is urgent, so it grows in companies, schools, etc. Looking at how Ruby does its marketing is quite interesting, but this language is still too young to be able to differenciate the reality from the buzz effect yet.

Looking at how Linux did, and still does its marketing, is more interesting because you know what worked and what didn’t.

So this blog will focus on a few things that could be done. And this first post focuses on Python Certification.

Important notice: i have digged to find some infos on this topic, but if I missed something that is beeing done, please forgive me and comment this post.

A Python Certification

Linux certifications, brought for example by Dan York and the LPI, have became great tools to promote Linux in business.

The benefits are quite simple :

• Certification centers promote Linux and pay big money in advertisment to attract students
• The LPI is a non-profit organization and can therefore create a standard in certification, that is followed by everyone
• The students became in their own Linux evangelists, and there’s a crowd of students out there that are just waiting to know the truth
• Companies can rely on it to hire
• Developers can obtain it to get recognized

So what about Python ? Take the last chapter I wrote, change “Linux” by “Python”, and “LPI” by “PSF” and you get the idea.

I really believe the Python Software Foundation should create a Python certification. That’s probably what we are going to dig on our side at AFPY and maybe come up with some proposition at the PSF. And you, readers ? what are your opinion about it ? I’d love to hear it.
Next time I’ll talk about the Python Program Certification, which is basically the same idea but applies to software standardisation and quality, and about cheesecake, which is a great idea.