Why people write documentation (Andy Oram)

I'm glad Andy went through the bother of doing this survey on why people write free documentation. It's a topic of constant discussion at Alfresco, and I'm sure at most open source projects and companies. It's a difficult proposition to get outside contributors to any project, and particularly a commercial open source project, but to get contributions to documentation...? Much harder, because it provides far fewer immediate benefits to developers (and no one likes writing documentation at the best of times).

So, why do people contribute their time and expertise toward writing free documentation. What's the top reason? Community building, interesting enough. Good documentation, like good fences, apparently makes for good communities. Few write documentation for "thrills" and even reputation, which is oft-cited as the driving factor behind open source code contributions, falls well behind the community rationale.

Looked at another way (ranked by just how important people felt they were), community building is the clear winner ("Extremely important"):

Andy concludes with the following:

I believe that behind the idealism, the empathy, and even the experience of fun cited by respondents lies a basic human imperative to educate others. This imperative allows children to pick up the skills and cultural traits they need to mature.... Even after the invention of formal education, many of the most important skills have been passed on the way that human cultures have always done it: by people mentoring and guiding those who are just a few years younger.

If (as I believe) quite primitive drives toward power and magic fuel a lot of software hacking, the drive toward passing on facts and cultural norms fuel the burgeoning area of online documentation.

Regardless of personal motives behind the larger "Community" rationale, it helps to extend the longevity of a project. Individually, we're probably motivated by an interest in sharing what we know. I know that this is the primary reason I write this blog - what little I know, I want to share. Sometimes I have facts bubbling around in my brain that I need to get down "on paper" so that I can ensure the facts don't stagnate and die with me.

Perhaps documentation is no different. The key, however, will be in figuring out ways to motivate more documentation contributions by appealing to community.

[aardvark23]

Open souce documentation

I will have to take issue with the comment "no one likes writing documentation at the best of times". Not every software developer hates writing documentation. I am one of those few that likes writing documentation. I see documentation is an essential part of linking an application's design with it's implementation.

I wish more open source developers would put more effort into documenting their applications. It would be so much easier to help in the understanding how an application works. This is especially true when you are trying to debug an application.