Open source and documentation

February 10th, 2003 § 3 comments

Shelley Powers recently commented on a very common problem in open source projects: the lack of documentation, whether regarding the installation or the use of those projects. As she said, there a kind of perception that the programmers responsible for those projects should not be bothered with demands for documentation as they are already doing people a great favor by building them.

I don’t want criticize or belittle the efforts of programmers who create open source software. To the contrary, the generosity of many of those programmers is astounding and worth of praise. Nonetheless, documentation (or lack thereof), is really an issue in open source problems, normally stemming from the insufficiency of resources and time to do it. Documentation is a time-consuming tasks, and it’s perceived as something that will take time from more profitable activities like improving the application. And, for most people, it’s a boring task too.

All that facts result in a huge deficiency in that area, although I believe many programmers involved in open source projects are as good technical writers as they are programmers. Nevertheless, only big projects, like Apache and JBoss, are likely to have specific teams that, while still participating in development, are primarily responsible for documentation.

I think this mentality must be challenged. The open source community must recognize the problem and take the necessary steps to correct or at least ameliorate the situation. Each programmer in a open source project should find ways to help the project users with respect to documentation, whether those users are programmers or not.

Open source programmers must realize that, even if users only resorts to documentation when nothing else is left to do, it may be the difference between a useful tool and an abandoned one. However noble is the intention behind a open source project, without documentation the chances it’s adopted beyond the initial user group are reduced if the documentation is lacking — especially in corporate environments where training and discovery of quick solutions for occasional problems is crucial. Documentation is also necessary if the knowledge about the application is not to be lost. In fact, this is the whole reason behind the Linux how-tos. Finally, the current growth of open source desktop applications creates a new demand in that area.

Volunteers are as needed here as in any other area of the open source development process. I believe the adoption of simple documentation practices could result in a huge gain for open source. A simple and obvious way of helping is documenting difficulties and solutions when installing or using a given program, and later donating this documentation to the program developer. Most how-tos were created in that very way. Additionally, people interested in helping open source projects may do it helping with the documentation. BottomFeeder is an example of that. Its documentation is written by a volunteer. This is an excellent practice, and many projects many benefit from similar offers. Also, initiatives like The Linux Documentation Project are always needing more people.

My belief, stated many times here, is that technology that doesn’t improve users’ life is pointless. Documentation is part of this because its lowers the barriers to entry. Moreover, it’s a market demand. And people should never forget that open source projects answer to those same demands.

§ 3 Responses to Open source and documentation"

  • Documentation for Open Source

    Free as in puppies

  • Kevin Conder says:

    I wanted to give back to Open Source community but, at the time, I was only able to contribute about 10 hours a week. So I thought the biggest impact I could make with a limited amount of time was to help with documentation.

    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/

  • Ronaldo says:

    Thanks for your insightful comments. Your insider point of view is an extremely helpful complement for the point I was trying to make. I’m writing a new post on the subject and will make sure your points are an integral part of it.

What's this?

You are currently reading Open source and documentation at Reflective Surface.

meta