First of all, I am not an armchair quarterback… I maintain a large 1,000+ page manual for a free (as in root beer) audio synthesis program called Csound[1].

But I have battle scars from several failed attempts to help Open Source projects with their documentation. So let me get this off of my chest:

1. Documentation volunteers get no recognition. Consider a popular Open Source project… Who are its programmers? Who are its documenters? Unless the documenters are the same as the programmers, I bet you can’t name them.

2. Documentation volunteers get no respect. Project leaders assume that documenters are people who are too stupid to code. A programmer once deflected my technical question and suggested that I ask it on the project’s “users” mailing list. Unless you contribute code patches, you are considered worthless to most Open Source project leaders.

3. Documentation volunteers are unwanted. I’ve seen increasing numbers of project leaders using Wikis for technical documentation. Instead of doing the hard work of creating user documentation, they simply set up a Wiki and hope that users will write their own documentation.

No project leader in their right mind would allow anonymous CVS commits to their code-base. Nor would they just blindly accept code patches from random strangers. But they think such a system will lead to quality user documentation. You need an active maintainer or team to ensure that your documentation is complete, correct, and up-to-date.

So here are my suggestions for recruiting a documentation team for your Open Source project:

1. Start a documentation sub-project with its own mailing list, CVS directory, and visible area on your project’s Web-site.

2. Define a standard format for creating documentation. DocBook[2] is used on most high-profile Open Source projects. A style guide is also helpful: “Is it called a floppy disc or a diskette?”. Never switch standards without discussing it on the documentation mailing list first.

3. Identify the documentation tasks that need to be done and maintained. Post them on both your project’s Web-site and the documentation mailing list.

4. Put a responsible person in charge of coordinating the submissions, tasks, and volunteers. Make sure this person responds to email questions within 24 hours.

5. Recruit volunteers and delegate tasks. Make sure their names are associated with their tasks on the project’s Web-site.

6. Answer your documentation team’s questions. Make sure they are being treated respectfully.

[1] http://kevindumpscore.com/docs/csound-manual/index.html
[2] http://www.docbook.org/

Free as in puppies