Why people write documentation (Andy Oram)

While the reasons behind developers contributions of code to projects is (somewhat) well-understood, the reasons behind contributions of documentation are much less so. Andy Oram of O'Reilly Media surveys the industry to discover the motivations and rati

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.

Featured Video
6
This content is rated TV-MA, and is for viewers 18 years or older. Are you of age?
Sorry, you are not old enough to view this content.

Everything you can expect at Apple's Sept. 9th event

Apple is expected to throw the kitchen sink at us with new iPhones, iPads, a new Apple TV and MacBooks. We'll breakdown what you can expect to see.

by Brian Tong