Chad Perrin: SOB

4 February 2010

Documentation Documentation

Filed under: Geek — apotheon @ 01:21

No, the title of this is not two thirds of a joke about Steve Ballmer’s “Developers Developers Developers” dance. I’m talking about documentation for documentation.

The Set-Up

There are at least two types of open source development projects in the world.

  1. There’s the fakey-type open source development project, where someone writes code in a closed team (perhaps a team of one) and makes that code available to the world under an open source license, but there isn’t really any way for anyone to actually contribute to the project.

  2. There’s the for-realsies type of open source development project, where anyone can contribute — though contributions may of course be rejected if they aren’t “good” (by whatever definition the core team uses to use).

The Documentation

It’s a pretty generally accepted truism that documentation is important. People argue about whether their pet projects have good documentation, what constitutes good documentation, and so on, but they tend to agree that documentation is important.

A key part of most open source development projects is openness about accepting contributions to documentation. Accepting documentation contributions can help improve documentation without taking time away from actual coding by the core team. This is a good thing.

The Problem

It is often the case that there is a very clear-cut, easy way to contribute code to a project, but someone who wants to contribute documentation is left wondering “What the hell?”

The Solution

If you run a Type 2 (“for-realsies”) open source development project, stop right now and look at the documentation your project has for documentation. How well documented is the procedure for contributing improvements to documentation? How easy is it to find?

Seriously, this should be one of your top priorities when running an open source project that actually wants contributions from the user base. If you have a core development team, it is actually more important, most of the time, to encourage documentation contributions from the general public than code contributions. The only time code contributions should take precedence is when you no longer have anybody (competent) on the core team.

If you don’t have clear, useful, fairly complete documentation documentation (that is, documentation for the process and standards of creating and contributing acceptable documentation improvements), start working on it now. Please.


All original content Copyright Chad Perrin: Distributed under the terms of the Open Works License