1. Intro

The next Plone tune-up on Friday will focus on the documentation. In this blog post I will

• Explain what a tune-up is
• Recruit you to participate this one
• Write down some outlines I hope make happen in Plone community regarding documentation in the future

2. Tune up and the immediate future

A tune up is a monthly event where the community members will clean up low hanging fruits in Plone issues tracker (or some other open source project… though not sure which ones are proficient in tune-up practice) . The 62nd tune-up will happen on the next Friday and focuses on cleaning up some developer documentation. The event lasts 24 hours, is coordinated on #plone-tuneup IRC channel. Just pop up there on your local time.

Tune up has a friendly atmosphere and IRC channel will have members mentoring you around to get into the things. At least personally I can promise not to be angry and restock my fridge beforehand.

What will happen

• You decide that instead of having real life you’ll spend some time in IRC by contributing to the open source project (with bat ass crazy friends). If you need help getting into IRC in the first place try Plone online chat to get started.
• We will try to get some key players appear in the tune up by sending them personal invites. They will serve as mentors and information fire hoses.
• Tune up hosts have prepared issue tracker tickets we will tackle in this tune up. Specifically on the 62nd we are focusing to get developer.plone.org to a shape it can take over from the old documentation section for Plone developer needs.
• We will draw a grand prize of a fancy T-shirt among all tune up participants. (sorry, no katanas this time – we are kind of out of stock.)

(It’s movember BTW).

3. Far far future

This is what I hope will happen before we all are six feet under, contributing to the growth of cow parsley.

4. Plone docs target audience: known for who you are writing to

The audience of Plone the product are developers (can be sublassed to system admins, site integrators, theme editors, Python developers). I care about the end user documentation, the one without deep IT experience,  up only to the point the developer group has the required knowledge to pass the information to their own end users. Because if you are already running Plone it means you probably can tell people how to copy and and paste in TinyMCE. We have worse concerns in our hands.

The current documentation effort should focus to make Plone easier to adapt in a situation your web development house has no existing Plone experience.

I really don’t care about the old folks who have been using Plone 2+ years. They know where they can go to ask for help. But we need to focus on new users. Otherwise Plone the community will start suffering inbred problems. Our open source model does not scale enough unless our manuals are productized to the point people can independently get things done.

5. Plone documentation must catch up

We are currently in serious mess what comes to Plone documentation, as there has not been active maintenance of the documentation area for a while. We have hands full of old, non-functionality documentation and lack the up-to-date documentation how the current Plone versions actually behave.

It’s way too much for one, two or three persons to tackle.

We will clean up this by organizing tune ups and possible have sprints with sole focus on the documentation. In the best situation we’ll lock some old time developers to a cottage, let them keep their internets but take away their vims and force them to eat mämmi if they do anything else on their computers besides writing Plone documentation.

6. Documentation practices must be built into the community

It is not good enough that the documentation team runs like headless chickens after each Plone release to catch up with the documentation. The only way to have maintained, up-to-date, documentation that the docs come from the horse mouth itself.

In the future, the documentation MUST BE the responsibility of the person who contributes the code to the project in the first place. No one is coming to write documentation for your Python module, no matter how nice your for loops are. Otherwise it is like hoping that your mother cleans up your toys after you have been playing around with them.

We are still planning how we are going to make this happen. Here are some suggestions

• Plan a) The developers somehow voluntarily start to write the documentation and the release manager and the documentation manager keeps tab on them. New features are blocked to go into Plone if they do not have minimal end user documentation and adequate developer documentation, like a tutorial.  It will help when we have finally described the process how this all should happen.
• Plan b) This plan involves you, a release manager with dragon-like abilities, a sauna and fresh stinging nettle plants.
• Plan c) The information is directly extracted from the brain of the developer. The process is not entirely hygienic.

7. Further info

See also the recent announcement regarding moving the documention on plone-users list.

Please free to post any comments regarding alternative futures.

 Subscribe to RSS feed Follow me on Twitter Follow me on Facebook Follow me Google+