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.



  1. I just want to note that one of my fav projects right now, Tor ( )) while it has no clear cut way for contributing (aside from anonymous login to their Wiki (which is sorely outdated)) documentation, has already let me know that my contributions at documenting the setup and use of Tor in as close to laymen’s terms as possible is not only OK, but rather welcome. Of course this means I’m going to have to keep using Windows a bit more until I have configured just about every piece of web-accessing software I have, and then relating that in easy to understand terms (with plenty of screen shots). I plan on making a site for the documentation (probably both as a hidden service and a public site) as well as putting up a contact email address with lax rules for contributing:

    Updates to screen shots need to be put in some sort of archive Anyone wanting to convert all the documentation to DocBook format is welcome to do so and we’ll host it Prefer some sort of CopyFree or CopyLeft license to apply to the documentation Needs to be accurate (though that will be hard to check if I or someone I trust doesn’t have access to a particular program) Needs to be in “layman’s” terms.

    Of all those, I think accuracy and being in layman’s terms are really the most important. I really need to get to work on that though as Tor is continuing to evolve (generally all I see announced on the list is security updates).

    Comment by Joseph A Nagy Jr — 4 February 2010 @ 02:01

    1. What possible benefit do you think using a copyleft license would provide for the documentation, other than advertising for copyleft licensing?

    2. As for testing, I’d suggest marking things that have been tested as tested, with details available for those who want to know the specifics of testing.

    3. Be careful. The Tor team might want you to become the new project documentation manager if you do too good and thorough a job for a while.

    Comment by apotheon — 4 February 2010 @ 03:38

  2. While I don’t agree with copyleft licensing, I don’t want to be a jerk about it. I would prefer a copyfree license.

    That’s actually a good idea.

    Depending on my experience on putting this all together, I probably wouldn’t mind. It would be the first time I’ve contributed back more than some help on a mailing list or a bug report or two.

    Comment by Joseph A nagy Jr — 4 February 2010 @ 07:48

  3. While I don’t agree with copyleft licensing, I don’t want to be a jerk about it.

    Generally, it’s a good idea to simply set a license for documentation and require that all documentation improvements submitted either assign copyright to the person maintaining the documentation or submit it for inclusion under the same licensing terms. Otherwise, you can’t ever do things like reorganize the documentation — because it would cause the various licenses involved to come into conflict. It’s best to pick a license and stick to it.

    Comment by apotheon — 4 February 2010 @ 08:33

  4. alright.

    Comment by Joseph A nagy Jr — 5 February 2010 @ 06:44

RSS feed for comments on this post.

Sorry, the comment form is closed at this time.

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