Why Do People Write Free Documentation? Results of a Survey
by Andy Oram06/14/2007
A unique survey ran on O'Reilly's web site during the first three months of 2007, aimed at people who contribute free documentation to online mailing lists, web sites, and other forums. The survey garnered 354 responses, which in itself indicates the thriving state of free documentation and the dedication of the people who write it.
Professional computer users know well that computer documentation, like music and news, has moved online. What's truly phenomenal is the high rate of contributions by rank-and-file computer users. Thousands edit wikis, answer questions on forums, and blog about experiments with technology--mostly for free. Their contributions may go on sites that are advertising-supported, but they rarely share in the revenue. Some receive fees elsewhere for articles and books, but the writing done gratis often comes up in search engines at rankings equal to or higher than official corporate sites such as Sun Microsystems' Java documentation.
So why do computer users take time away from their own lives and work to help people around the world whom they don't even know? I've speculated about this for years--notably in the articles Splitting Books Open: Trends in Traditional and Online Technical Documentation (2004) and Rethinking Community Documentation (2006)--but this year I decided it was time to actually ask the people who do it.
This article summarizes some of the debates concerning online gifting, presents the results of my survey, and attempts to analyze the meaning of the results. In order to maintain a flow, I've relegated most discussions of methodology to sidebars. The article consists of the following sections:
Common Questions and Issues Regarding Community Documentation
Reviewing a bit of the research and conventional wisdom regarding online participation will help us understand the value of this survey and the courses of action suggested by its results. If you find this section too philosophical for your taste, feel free to skip right to the discussion of the survey.
Channeling an Ocean
Online documentation is plentiful, timely (you can often find a bug fix within hours of the release of a buggy product), available anywhere in the world that has Internet access, and (as if this hadn't been emphasized enough already) free. Why should we do anything but lie back and wash in its abundance?
In fact, several phenomena show that online documentation could use improvements:
- The same questions get asked over and over
-
This wastes everybody's time, frustrates experienced users, and causes intemperate outbursts on forums. New users don't have enough guidance to find existing answers--or possibly don't realize that the answers apply to their problem.
- Users don't know where to start
-
Information is usually forthcoming to those who ask, but first one has to know how to ask. Users bounce from forum to forum because they don't know the source of their problem. Reaching the proper forum, they may have to reformulate their question to use terms that are understandable in that forum, and submit new information during several rounds of interrogation to clarify the problem. At other times, eager users dump huge volumes of computer output and configuration information into an email message, prompting forum participants to complain that they're overwhelmed by irrelevant data.
- Information quality is uneven
-
Amateur writing can lead to problems as simple as an ambiguous phrase that readers interpret incorrectly, or as subtle as hidden assumptions that leave documents inscrutable. Incorrect or outdated instructions that can actually hurt people's systems still turn up.
- Optimal solutions are often undiscovered
-
People reinvent the wheel a lot. Many powerful libraries and tools lie in obscurity. And while fixes to particular errors are easy to convey, best practices are not.
These phenomena can be addressed in many ways. Perhaps forums can find motivations for expert users to participate more. Forums could try to organize frequently accessed information and make it easier to find. Providing background could help users recognize what they need, letting them formulate effective questions and search terms the first time. Forums that respond to technical problems could change the interactions from mere fire-fighting to real education, leaving users more equipped to handle future problems.
Because the survey covered in this article dealt with motivations to contribute, I will focus on that issue. I have explored the rest in other articles.
It's the Economy
To explain why people contribute free information, the term gift economy is frequently invoked. Talk turns to economics to imply that contributions do not simply come from the heart, but can be grounded in an objective, self-interested response to the online environment.
Some researchers seem almost obsessed with proving that giving out information produces value in return--and therefore that it can be proven to be rational behavior. I'll use the data in the documentation survey to examine this economic question, to prepare us for the day the experts release a paper proving that the information being given out on the Internet is worth more than the value returned, and the World Wide Web (along with BitTorrent) collapses as a result.
So what value can someone get from writing computer documentation?
The most tangible reward is future payment. Therefore, some researchers suggest that people giving out free advice are trying to show their skills to potential employers, or are bolstering a business as consultant or trainer. Economists call this phenomenon job signaling, because economists like to make things more complicated than they have to be.
The Humble Egoist
Blatant self-promotion is often softened in the research literature as a bid for reputation. Although reputation is a fascinating and infinitely diverse chain of causes and effects, well worth exploring (one could start by asking why I took countless hours away from my regular job to develop this article), some selfish goal must come at the end of the chain. People build their reputations in order to get something out of it--if not a job, perhaps a paid engagement to speak in an attractive foreign city, or some other perk.
Other people engage in altruistic behavior simply for praise or enhanced self-esteem. Although these rewards seem self-justifying, because of their emotional kick, we can't understand them without an enveloping context of goals and values. If I praise you for firmly reprimanding a child, but you've decided you came down too harshly and only made matters worse, my praise doesn't benefit you. So we have to seek out interests once again and ask, "What larger goal brings someone to work for the reward of praise or self-esteem?"
The Job's Not Done Till the Paperwork Is Finished
Another benefit of offering free advice accrues to the people who create or make a living from technology. Teaching people to use the technology brings in more users and keeps them happy. It also allows developers to hear about bugs, feature requests, and difficulties in understanding user interfaces. The Apache, GNOME, and KDE projects have practically turned this kind of feedback cycle into a science.
So does project support constitute motivation for writing documentation? When the project is free software, an affirmative answer seems to beg the question. But there are many well-established reasons to create free software, such as the chance of receiving bug fixes and enhancements that make the software more functional for the original programmer. Therefore, project support is a fairly tangible motivation for writing free documentation about one's own software.
I should make it clear my survey asked about contributions of free documentation, not free software. However, it's natural to use insights and research from one area to illuminate the other. And the two types of contribution often go together and are made by the same people.
Give Me a Back-Scratcher Long Enough, and I Will Move the Earth
As Tim O'Reilly has pointed out, "scratching your own itch" does not provide a motivation to write documentation, as it does to write software. (Incidentally, in the decade since that article went up, O'Reilly Media has released a large number of books under open licenses, including brand-new works.) People who write documentation know what they're writing about, so their effort is directed toward educating other people. Therefore, unlike software, an author does not release documentation in the hope that someone else's fixes, updates, or enhancements will directly aid the author's own work.
But Tim's observation has to be tempered in two ways that suggest that the sense of mutual back-scratching still extends to documentation:
-
Some people record the lessons they've learned from exploring and troubleshooting online, so they can be sure to find them later. In other words, some people have to relearn what they learned before. Putting it online allows other people to correct, update, and add depth to what they've learned.
-
As suggested by Rishab Aiyer Ghosh and others, people may not enhance an author's particular posting or wiki entry, but the author will be recompensed by other postings. Each contribution you make reinforces a culture of mutual aid that produces eventual benefits for you.
From Holism to Holiness
Faced with the surprising growth of free software, which has altered the landscape of an industry, some people re-evaluate their expectations of human behavior to the point of declaring free software communities to be more refined than other software developers and users in their motivations, and even their ways of dealing with collective decision-making. Free software developers and users supposedly recognize the value of working together, of sharing what they have without seeing any immediate reward, and of appreciating what every participant brings to the effort.
Yet vibrant communities also exist around proprietary software. Free tools and extensions to proprietary software have created enormous gift economies in themselves. When I troubleshoot Windows problems with a web search, solutions often turn up in material donated by unknown volunteers, just as with free software. And like me, large numbers of people interact with both free and proprietary software. Free software development introduces new modes of operation into the computer field, but we need to do a lot more investigation before concluding that the developers and users think, feel, or interact differently from their peers in the proprietary space.
