Open source and documentation, continued

March 1st, 2003 § 2 comments

Some weeks ago, I wrote a bit about open source and documentation in agreement with a post by Shelley Powers in her blog. I got some interesting comments — in both my Portuguese and English blogs — but because of time couldn’t write more about the subject until now. In this follow-up, I decided to elaborate on those comments and expand them with some additional thoughts of my own.

My whole understanding of open source in centered in the fact that I consider it a philosophy. It’s not — as some people seem to think — another option or model of development. As a philosophy, open source is coherent with my vision that software that doesn’t improve users’ life in pointless, whatever the software or its intended use. Documentation fits this vision in that it lowers the barriers to entry both in the use of an application and in its evolution. Just to clarify in what sense I’m referring to documentation here, I’m using it to mean both the internal documentation about an application, which describes its inner workings and interfaces, and the usage documentation intended for the end-user.

Unfortunately, documentation is often seem as something of secondary importance in the development of open source projects. One doesn’t need to look to far to see that this is a problem that plagues even big open source projects. And, as with any issue about open source, it’s a problem with many roots and causes.

Cristiano Dias, commenting on the issue in my Portuguese blog, wrote about the hubris inherent to the open source movement (in fact, to programmers taken as a group), a vestige of the old mentality that “real programmers don’t need manuals,” which is also at the core of a similar problem: the lack of comments in most of the public source code. The very nature of open source projects, which tend to concentrate a significant amount of good programmers, causes people to see the source code as documentation. Obviously, as I said before, this only rises more barriers to entry. For common users, the code is an impenetrable wall, and users who are programmers themselves usually the lack of time or willingness to dig through the code unless it’s absolutely necessary.

This predisposition towards programmers was something that called my attention years ago when I read about the beginnings of the open source movement. More recently, in the book Free as in Freedom, this can be clearly seem in Richard Stallman’s stance towards code sharing: he considered programmers as the only initial beneficiaries of open source. This stance changed slowly with time, but it’s still prevalent in many open source circles.

In another comment posted in the Portuguese blog, Geraldo Xexéo notes that the lack of good documentation is a problem to closed source projects as well. It’s needless to say that I agree with him; however, that fact should not be used as an excuse by open source advocates. As the saying goes, two wrongs don’t make a right. This is especially true of open sources projects which are supposed to be replacements for similar commercial software. If open source’s stated purpose is to offer more options to users, it’s obvious that documentation plays an important part in this offering. With respect to the code itself, it’s already been ascertained that code is harder to read that to write, which makes documentation all the more important in that case.

There is also the issue of leadership. Howard Hansen, in a trackback to the English blog, wrote about the role of the program manager at Microsoft as an aggregator of information for the project, including documentation. He writes about his own experience at Microsoft to exemplify the importance of that figure to the projects, and notes the conspicuous lack of a similar person in most open source endeavors. This is in fact one of the most glaring needs of open source projects. As most such projects are born of a personal need that later expands in a product with an audience, the normal development flux is not found in those projects. However, it’s here that open source as a philosophy comes into play again. There is a need of volunteers not only for the glorious programming tasks, but also for the boring tasks as documentation and management. Eric Raymond, in his The Cathedral and the Bazaar, writes about a development coordinator, which broadly corresponds to Microsoft’s program manager. They are usually found in huge open source projects, as Apache and JBoss,, but sometimes even their presence is not enough to warrant better documentation as they usually are programmers focused more on the code than management issues.

Another problem is recognition. As Raymond also notes in The Cathedral and the Bazaar, recognition is one of the biggest incentives in open source projects. This fact creates a problem for documentation, which is generally considered an inferior task. In a comment made in the English blog, Kevin Conder, an open source developer weighs in with good insights about this very issue. He writes about his own experience:

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.

Conder documented the Csound projects, creating a 1,000+ pages manual for the program. The results turned out to be disappointing. He continues:

  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.

Although the comments above seem an exaggeration, I don’t think they are much far from the reality of many open source projects. Programming tends to automatically create a club mentality in which only people able to code are considered as having any value. The stance Conder notes in point 2 is prevalent in those circles. Unless direct technical proficiency is shown, people are not seem as potential helpers. The result is point 3: projects in which documentation is expected to build itself out of nothing. Ironically, this very stance leads to saturation of the projects’ support channels — if they exist — when most of the doubts could easily been solved by documentation. Of course, people tend to resort to manuals only all other options are already spent. However, the existence of documentation serves to reduce the noise in support because preserves knowledge. Instead of repeatedly typing the same answers, people can just refer users to the appropriate documentation page.

If those are the problems, are there any solutions? I think so. The first solution, as I mentioned, is trying to create a higher awareness of documentation issues to educate people about the needs. This applies both to developers, who must be convinced to help in the effort, as to project leaders, who must learn to avoid the problems Conder wrote about.

To that effect, Conder gives some advice to leaders of open source projects; advice they would do well in listening to. He writes:

  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 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.

This is sound advice that can be applied in any situation. They will guarantee not only higher overall documentation quality, but also a good integration between the project teams and the satisfaction of all (or almost all) persons involved with it. Of course, they are not easy to apply, and required a conscious effort on the part of the project leaders. Nonetheless, if open source projects intends to grow, those are necessary steps in the path of evolution.

Geraldo Xexéo also notes the need of strengthening open book movements, which are another form to document applications, even if it’s intended for end-users.

Another interesting thought is that documentation can be use as a way to gather resources for a project. Take JBoss, for example, in which documentation of offered as a paid resource. The money obtained with this approach is used to pay for future development. In larger projects, that option may be worth considering.

At last, but not at least, we can help as users either offering recognition, reviewing documentation or helping with it. Open source projects need to be nurtured in whatever ways we may found.

From everything I wrote until now, it’s clear that I’m an open source proponent. Documentation is an area I want to invest more in the future. If every open source advocate would donate a few hours of his time in this area, the result would be awesome. Well, that’s my answer to the comments made in my blogs. Feel free to add your own comments, criticize, suggest improvements, and generally tear my arguments apart if you feel particularly inspired to do so.

§ 2 Responses to Open source and documentation, continued"

  • Amit Patel says:

    There are several types of documentation. The documentation that’s easiest to produce maps code (functions, classes, modules) to documentation. I see plenty of this in Emacs modules and functions.

    The documentation that’s hard to produce goes the other direction: given some need, like wanting to highlight all tab characters in emacs buffers, how do I determine which module/function will help?

    It’s this “reverse” documentation that open source projects are particularly poor at. When commercial software is released, there’s a process to go through that can look at the product as a whole and answer these sorts of user questions. With open source, we have little releases all the time; there’s no place to stop and look at the product as a whole. Any “reverse” documentation will be out of date after a while, and there’s no obvious way to update it because it’s not linked to the updating of specific modules or functions.

  • Ronaldo says:

    I agree. However, I still think you need people in charge of documentation in open source projects. Even with a short release cycle, if people are interesting in maintaning good documentation, they will take time to coordinate the development so that documentation can be produced in a relatively ordely fashion. After all, even open source projects have some kind of goal that can be fatored in the production of documentation.

What's this?

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