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.

Tags:
Tech Culture
About the author

    Matt Asay is chief operating officer at Canonical, the company behind the Ubuntu Linux operating system. Prior to Canonical, Matt was general manager of the Americas division and vice president of business development at Alfresco, an open-source applications company. Matt brings a decade of in-the-trenches open-source business and legal experience to The Open Road, with an emphasis on emerging open-source business strategies and opportunities. He is a member of the CNET Blog Network and is not an employee of CNET. You can follow Matt on Twitter @mjasay.

     

    ARTICLE DISCUSSION

    Conversation powered by Livefyre

    Don't Miss
    Hot Products
    Trending on CNET

    Hot on CNET

    CNET's giving away a 3D printer

    Enter for a chance to win* the MakerBot Replicator 3D Printer and all the supplies you need to get started.