Published on (
 See this if you're having trouble printing code examples

Why Do People Write Free Documentation? Results of a Survey

by Andy Oram

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:

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.

Survey Results and Interpretation

With the questions from the previous section churning in my head, I wrote a survey in late 2006 to ask why people contributed their time to write documentation. Although a lot of online documentation is on corporate or advertising-supported web sites (including those put up by O'Reilly Media), I explicitly excluded such sites, asking for responses only "from people who do this for non-monetary reasons." [Full text of survey]

Data Collected

The survey collected three types of information:

What kinds of documentation people contribute

My goal was to cast the net as wide as possible. A visitor clicking through to the survey was greeted with the question, "Do you answer questions on mailing lists about how to use a software tool or language?" By starting with the most casual, intermittent contributions to online documentation, I signaled that visitors should be very inclusive in thinking about their contributions. The survey continues to talk not only about writing but about translation, editing, technical review, and administration.

The projects to which the respondents contribute

I was hoping to learn whether different types of projects garner different types of help--in particular, to test the thesis mentioned in the previous section that free software is unique in its patterns of participation.

The reasons for contributing

This section was the crux of the survey. It listed eight reasons that I thought were likely candidates for people writing online documentation, along with a text box where respondents could list "other factors."

Two of my reasons tested the mutual back-scratching mentioned in the previous section: mutual aid and community building. I also put in gratitude, which I considered another angle from which to view mutual aid, but which I thought many respondents would see as a separate motivation because of its emotional connotations.

Community building particularly interested me because I had mentioned in an earlier article on mailing lists that the key goal of a technical mailing list was to meet user's technical needs. A researcher in the field of democracy and policy bluntly informed me that I was wrong, and the main goal of the list was to build community. This challenge to my purely instrumental approach intrigued me, but I wanted to test whether contributors had more directly self-rewarding goals as well. I included two reasons that I thought would elicit self-seeking motives. The first was reputation building. I removed any ambiguity about its self-seeking basis, as I described in the previous section, by defining reputation building as follows:

Consultants, trainers, job seekers, authors, and others who hope to build a career go online to build up recognition and respect.

The other selfish reason I offered was personal growth. The inclusion of this reason drew on teachers' well-known observation that they learn as much by teaching as their students do.

Situated halfway between generalized, half-altruistic community building and directly self-seeking behavior was another reason: informal support. I could have tried to tie this reason directly to personal rewards by narrowing the definition to support given by product developers, as I defined in the previous section. But this would have been too hard to define, because as I pointed out there, it's hard to tell why someone is associated with a software project. I can't ferret out which people feel that they get a personal payback from offering project support and those who do it altruistically. So this reason remains ambiguous as a motive for writing documentation.

Finally, I felt I had to include two reasons that didn't fit in with any particular research agenda, in order to capture all the motivations I think of. The first was enjoyment of writing. I know from my own experience, and that of my authors, that this must usually be present for successful writing, although in the field of technical documentation it would hardly be the primary motivation. The last reason I offered was thrills, which I defined as follows:

There's pleasure in seeing your insights turn up almost instantly on a forum with worldwide scope, as well as watching others succeed with your help and praise you for it.

This reason was prompted by an idea I drew from Joseph Weizenbaum's classic Computer Power and Human Reason and wrote up in another article, suggesting that a quest for power drives contributions to free software.


My documentation survey, after some editing by O'Reilly staff familiar with surveys, went up in January 2007. I contacted many leaders throughout the software field, asking them to promote participation among people with whom they had influence, and called on my fellow editors at O'Reilly to make similar appeals to leaders in their technical areas. Tim O'Reilly featured the survey on his popular O'Reilly Radar blog, and an announcement appeared on various O'Reilly Network sites.

I allowed the survey to run for three months, as long as new submissions were being added. Finally, noticing that additions had essentially come to a halt in April 2007, I shut down the survey.

I should make it clear that the sample was self-selected, so we have to be careful when drawing conclusions from the collection of responses. To keep the survey short and make it easy to respond, I decided not to collect demographic information that could have been interesting, such as age, gender, or national origin. Any survey that tried to remedy these deficiencies would have to be backed up by a much more costly and professional strategy for recruiting respondents.

[Complete results as a CSV file] My only changes to the responses were to remove a few phrases that identified individual respondents, in order to adhere to the survey's promise: "Individual responses are strictly confidential and names of participants in this survey will remain private."


Personal connections and coincidences determined where the 354 responses came from. Communities where I am well-known (such as Perl and GNU/Linux) or where leaders encouraged participation (GNU/Linux and GNOME), contributed the bulk of the responses. When leaders failed to act on our requests for publicity and communities didn't take much note of our postings, few responses emerged.

Therefore, one can't draw any conclusions from the pattern of responses from different projects. The most serious consequence of the skewed responses is that only a dozen respondents claimed to contribute documentation on proprietary software. This crippled my attempts to test for differences between free and proprietary software communities, as described in the previous section. [Breakdown of submissions by major projects]

Most Popular Reasons for Contributing

The reasons for contributing documentation turned out to be the data that offered the most insights.

Providing a familiar four-point scale made it easy for people to fill out the survey, but it created a dilemma during interpretation. Suppose Respondent A uses a lot of 3s and 4s, whereas Respondent B has mostly 2s and 3s. Does Respondent A really care more about writing documentation than Respondent B? Should zealots have a greater weight in the results?

My reference to "zealots," of course, is a joke. The problem of weighting responses is endemic to any research based on language, because phrases such as "extremely important" mean different things to different people.

To resolve the dilemma, I use two measures for every calculation. The first measure is just the raw data chosen by each user: a 2 is always a 2 and a 4 is always a 4. If someone doesn't choose a category, the submission is rated a 0. The people who use consistently higher categories have a greater weight on results. I call this raw results.

The second measure adjusts the eight ratings made by each respondent so that every respondent has equal weight in the results. Calculating this measure is trivial: just add up all eight ratings by each respondent and divide each rating by the total. Any reason that a respondent leaves unrated, or rates at the lowest level ("Not important at all"), takes on a value of 0. These adjusted results for each respondent add up to 1.

Raw results are more fair, but they might not be more accurate. It all depends on how consistently respondents interpreted terms such as "extremely." I believe such phrases lead to a wide range of interpretations, so I trust the adjusted results more.

Raw and adjusted results proved to be almost the same for the most basic measurement (Figures 1 and 2): what were the most popular reasons for contributing?

Figure 1
Figure 1. Total raw results

Figure 2
Figure 2. Total adjusted results

Maddeningly, I have come out the loser in my dispute with the policy researcher. Community building emerges as the most popular reason, with 1,076 votes (51.0 on the adjusted scale), whereas personal growth earned only 1,070 votes (50.6 on the adjusted scale).

Speaking seriously, the documentation survey has proven its value by demonstrating strongly that software users care about the communities that they feel they are a part of. Not only was community building the top reason, but the closely related reason of mutual aid was third, and gratitude fourth. [Exact results in tabular form]

Another chart (Figure 3) comparing the adjusted results for each of the eight reasons shows how powerful the community motivation is. The legend in the chart shows the reasons, ranked in order of importance. Uniquely, not only does community building come out at the top, but it's the only reason that more people rated at the highest level (4, extremely important) than the next higher level (3, important). Such results uncontestably affirm the contributors' attachment to their community, in whatever way they define community (we'll look a bit at that at the end of the article).

Figure 3
Figure 3. Reasons ranked by importance

The personal benefits of learning through teaching emerge as a top-ranking motivation, too. But reputation--that intricate mesh of information and relationships that lies at the center of so much research--falls to the sixth or seventh rank.

What does this say about suggestions by researchers that participation on forums could be bolstered by ranking contributors and somehow honoring those who make the best contributions? When the MSDN wiki began, for instance, the wiki's managers explained to me how they were planning to highlight experts they had come to know in the user community and within Microsoft, to let participants on the wiki know that contributions by these people were worth special attention. The Slashdot-style "karma" rating system offers another model for rewarding contributors.

The documentation survey shows that reputation is not one of the top motivations for contributing. But I wouldn't abandon efforts to provide technical and social support for reputation building. There are many reasons it still might be worthwhile:

In regard to the third point made in this list, it would have been interesting to correlate responses with the quality of contributions. But I couldn't think of any effective way to ask respondents, "Are your contributions any good?" Nor was it ethical or feasible to seek out documentation from each respondent and judge its quality.

Nevertheless, the survey shows that participation is driven by many factors that don't bear immediate rewards. Responses to the "other factors" question, described later, demonstrate this.

Free Software Versus Proprietary: Any Differences?

As mentioned earlier, some people believe that participants on free software projects stress different motivations from participants on proprietary projects. I have found that people are people everywhere, and that generosity and empathy abound in all demographics. So I decided I would debunk the idea that something was special about free software projects by comparing the reasons given by free software contributors and proprietary software contributors.

My greatest disappointment in this survey is that only 13 people claimed to contribute documentation on proprietary products, and I had to eliminate 4 from my statistical results because they contribute to both proprietary and free projects. (You can't compare two samples if someone belongs to both.)

I couldn't in good conscience claim that nine samples were representative of all people who contribute to documentation about proprietary projects. But just for fun, I decided to create some charts (Figures 4 and 5). And I was a bit surprised by the results.

Figure 4
Figure 4. Free versus proprietary, raw results

Figure 5
Figure 5. Free versus proprietary, adjusted results

The free software contributors ranked mutual aid and community noticeably higher than the nine proprietary contributors--precisely the motivations where a difference would be predicted by the hypothesis that free software is different. Given the crudity of the four-point scale in my questions, and the tiny size of the proprietary sample, I can't make any claims about differences. I merely point it out as a suggestive coincidence.

Is Efficiency the Right Goal?

As my exchange with the policy researcher about the importance of community showed, I began my inquiry into online documentation by asking how it could be delivered more efficiently. I took the utilitarian view that the faster people got information, and the fewer folks they bothered along the way, the better off everyone would be. Thus, I hoped to improve documentation by reorganizing what was already available, enhancing search tools, providing professional editing, and beefing up background information.

But if people actually like helping others--if, as results suggest, they get satisfaction out of answering questions--these goals can be modified somewhat. I wouldn't rush to the other extreme and look on happily while knowledgeable list members answer the same basic question for the 800th time. There is still good reason to save people time and trouble by writing better documents and making them more visible. But the community can be expressly drawn into the educational task.

Human interaction is powerful and precious. While answering a need from someone on the other side of the world, a forum participant can convey learning strategies as well as a positive culture for community participation. I have seen participants try to do this, but the forums are not set up to encourage intensive educational experiences. The tenuous connection each participant has to a technical list makes it hard to sustain true engagement around a troubleshooting problem and turn it into a motor for personal growth.

Perhaps, if we recognize lists as communities--as more than instruments for solving technical problems--we can make them more effective at solving those very problems.

Respondents in Their Own Words

Having offered all the insights I can by aggregating data, I now turn to what is in some ways the most fascinating part of the survey: the 109 responses given when survey takers were offered a text box in which to express their passions. [Full text of "other factors" field]

If anyone viewing the charts earlier in this article believes people support community merely for the rewards it returns to them, and that altruism plays a minimal role in participation, a perusal of the "other factors" field would dispel such cynicism. A burning desire to help others runs through the responses, although other interesting personal motivations also arise.

Empathy was a powerful force for some respondents:

The biggest motivation to me is making technical information clear and readily understandable so that people that come after me don't have to waste the same amount of time trying figure out how to do something that could have taken much less time if the documentation had been clear and complete.

Filling gaps in documentation so that people in the future do not expirience the frustration that I did while trying to solve the same problem.

Many respondents referred to the international reach of forums, web pages, and chat sites. This appealed to them for either political reasons or personal ones:

helpful for society--free documentation helps poor people especially in developing countries

Curious to see what joining an international project would be like.

Work with people around the world with similar interests.

I enjoy communicating with people that live in different cultures. I like learning about other ways that someone might use the software.

Other expressions of altruism showed that respondents felt it was a fundamental part of their being:

It's part of my personality to give advice.

I guess I am a person who just wants to help if she can: I although volunteer in other, not computer-related fields like community work ect. - I enjoy being helpful and helping other people to finde solutions and alternatives for themselves

Helping out is spiritually important to me. Also, the more people, institutions, corporations, schools, etc. use free and open source software the better it becomes which is better for everyone (including me)

As the previous quote shows, altruism mixes comfortably with self-seeking goals. The observation behind my personal growth question--that teaching enhances one's own knowledge--turned up in many responses, along with other personal goals:

To provide information to potential developers in the hope that they will improve the software in future

Promoting the use of my language.

Needed to learn how to use the technology, so I wrote documentation (so I remember what I did)

Further reference when I need it! I often bang my head against a problem for hours, so when I finally figure out what's going wrong I write it down in my blog/web pages/whatever. The next time I come across the problem, I either remember that it happened before and look for it on my site, or Google points me to my site. :-)

It provides a way to have the technical data *I* can use later. Sometimes I forget the details.

To illustrate the relevance of personal growth as a reason for contributing, several people aired the idea that teaching forces one to deepen one's grasp of a subject:

When I decide to write on something, I have to prepare even more thoroughly.'s all very well to learn something. But I find that to truly understand it it helps a great deal if you've written about it. The act of structuring your thoughts about something before (or during) writing about it forces you to make sure that you do actually understand what you think you understand.

Self-Education - I learn the software during the documentation phase - that is - I use "while explaining, I understood myself" technics.

Sometimes helps me to understand something better. It often prompts me to look at the source code for the item in question and understand how it works.

The word "fun" appeared in quite a lot of responses. The respondents apparently considered it a broader and more appropriate expression of their pleasure than my term "thrills."

A few indulged in a bit of levity while filling out the field:

avoidance of other work

I want to contribute something back and I do less damage writing than hacking

That last quote revealed, in a humorous vein, a motivation often voiced by contributors: they don't have the skills to write software for other people's use, but can make themselves useful through support and documentation.

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. How, otherwise, could the human race survive from generation to generation? 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.

Ideas I Couldn't Follow Up On

I started the survey with scads of ideas for comparisons and tests, but the ungainly and fragmented data did not permit me to follow through with most of them.

I hoped I could run sophisticated tests between the three types of information I collected: types of work, types of projects, and reasons for contributing. None of these ideas proved worthwhile, not even the comparison of free and proprietary software.

There turned out to be no point to comparing types of documentation (wikis, etc.). For one thing, I couldn't get many independent samples because nearly everyone contributed to more than one form. (A full 86% listed more than one form of documentation they contribute to.)

More fundamentally, I can't expect to learn anything useful from the comparison. For instance, one person may prefer to contribute to a wiki but be working for a project that doesn't provide a wiki. The available forms of documentation are not always under the control of the respondents.

I think this question was worth including because it informed the respondents about the range of behavior I wanted to track, and perhaps let them count as "documentation" things such as postings to mailing lists that they might have discounted otherwise. Because such postings serve as solutions to technical questions, and often hang around permanently in archives to be read much later, they definitely qualify as online documentation.

Do Online Help Forums Constitute Communities?

Community is an overused word, and claims to build online communities have been challenged by skeptics on many levels. So it's interesting to look at a bit of research on communities and community building.

Jürgen Habermas and Benjamin Barber provide starting points for many such discussions, but their work doesn't map well to the types of forums discussed in this article. For them, community is the culmination of a process rather than a starting point. Habermas uses community to understand truth, and Barber to create a vibrant democracy.

Certainly, the defining features of community in Habermas and Barber (tolerance, good listening, help for new members or those whose skills need strengthening) can teach a lot to people who want better technical forums. Such guidelines for productively managing developers and users online are offered by Karl Fogel in his book Producing Open Source Software: How to Run a Successful Free Software Project, which I edited and O'Reilly published.

More direct insights can be gained from The Great Good Place by Ray Oldenburg. One-third sociology, one-third nostalgia, and one-third exhortation, Oldenburg's popular text documents the gatherings of people who don't have any practical reason to be together but are drawn to bars, bistros, or even public parks by the chance to mingle and share thoughts.

Because gatherers are freed from the hierarchy and strict protocols of work on the one side, and from the judgments and emotional pressures of family life on the other, they can open up in this "third place" and be themselves. This in turn creates a sense of community that spills out of the cafe door into the greater town, thus civilizing it.

Oldenburg's third places are rooted in their physical communities, but online forums can create some of the same conditions. Participants are very aware that they are judged, as in a bar or social hall, by what they offer and how they behave, not by credentials and affiliations. "A place that is a leveler is, by its nature, an inclusive place. It is accessible to the general public and does not set formal criteria of membership and exclusion...Third places, however, serve to expand possibilities, whereas formal associations tend to narrow and restrict them."

Online forums act as third places in this regard. For instance, technical experts who are unemployed--and thus have no status in the work world--know they can be valued on an online forum for their contributions.

The free conversation in third places breeds independence and democratic spirit, to the point that tyrannical governments have regularly tried throughout history to shut down bars and cafes. One doesn't expect Jacobins to arise on a mailing list to discuss Ruby programming, but participants on all these forums are aware of their presence in a neutral zone not controlled by any vendor or authority, and exercise their rights to challenge and criticize accordingly.

Also like Oldenburg's third places, online forums are always active: "Third places that render the best and fullest service and those to which one may go alone at almost any time of the day or evening with assurance that acquaintances will be there." On a forum, you can log in at any hour and find both help and interesting conversation. Like a third place, you can come and go as you please.

One specific observation of Oldenburg is particularly relevant to technical forums: his lament that suburban environments are hostile to youth. The design of American cities around cars, and other social barriers to leaving the house, leave young people without any healthful place to congregate. Ironically, Oldenburg's cure for many problems of society consists of keeping kids on the streets.

I suspect that these all-too-familiar conditions are responsible for the tremendous technological fascination and online creativity shown by children and teenagers, whether it be shooting videos, synthesizing music, or coding up computer programs. For these young people, also, online forums provide the critical outlet for their gregarious nature. Places where they can share their work stimulate their creativity, and the results of the creatity encourage more sharing. Once again, community and mutual aid become reasons for a virtual something to emerge out of nothing. And in the places where people seek information to support their work with computers, such sharing can provide immediate solutions that would not have otherwise existed.

So What Do We Know Now?

Readers can be forgiven for complaining that my survey of the documentation landscape has left them in the fog. Despite receiving 354 responses, many with fascinating and meticulous testimonials, I've established nothing for certain. Where do we go from here?

Is There a Better Sextant for This Survey?

The tentative insights suggested by this survey's results make one yearn for more and bigger surveys. No one would enjoy doing another survey more than I, but it doesn't seem feasible to me.

It's hard to think of a way a survey could bring in more people and more diversity. What seems to get people's attention is an endorsement of the survey by someone they respect, and how could this be done better than by employing the formidable social capital of O'Reilly Media, as I did? To get the more responses would require buy-in from the leading individuals we already contacted and failed to interest.

Similarly, I feel the survey was about the right length, and that loading it up further would cause participation to decline. I would also be reluctant to ask for many personal details. To make the survey longer or deeper, we might have to offer some incentive--and what a perverse way to recruit respondents in a field driven by the willingness to give information for free! Any incentive we would offer risks attracting people whom we don't want and whose input we don't trust.

Finally, a more detailed and incisive survey would call for more professional control in everything from fashioning the questions and recruiting respondents to analyzing the results. I don't know who would be willing to pay for it.

Experiments to Move Forward

In lieu of another survey, I recommend launching some projects to see their impacts on the issues I laid out at the beginning:

Encourage community

Because community building emerged as the dominant motivation for contributing to documentation, let's start with that.

Technical forums already play multiple roles, and are already employed to do a lot of explicit community building: participants share information about conferences and user group meetings, gossip about developers and other project leaders, argue about news events, recruit people for testing and other useful functions, and even crack jokes in conformance with Ray Oldenburg's observations of "third places." All this could be encouraged.

I'd recommend, though, that different types of discussions be clearly identified through well-established techniques such as keywords on subject lines, so that people can approach each type of discussion in the right spirit. Separating topics into different lists, however, would be going in the wrong direction because it segregates the community-building activities.

Asking people to mark their subject lines and separate the threads of discussion would also allow the list to tolerate contentious posters who bring up controverial subjects. You want these people around, but you also want to shut them out of your consciousness sometimes.

While we want a place for debate and criticism, most forum participants agree that it's important to maintain respect, at least when dealing with newbies. Self-moderation usually works well, but at least some veterans of a forum should stay conscious of the need to remind people of their manners. This is a difficult topic because different cultures have widely varying attitudes toward debate and authority, but the worldwide reach of technical lists is one of the features that makes them appealing to contributors.

Offer more bang for the buck

Although forum participants love to help people, they also get tired of answering the same questions repeatedly and will probably contribute more if they feel their contributions go farther.

So when useful summaries exist, such as formal documentation, wikis, or FAQs, encourage their use at every opportunity. If you point a newbie to the wiki where the answer to his or her question can be found--instead of just tossing the answer into your reply--not only do you make it more likely for newbies to use the wiki, you also make it more likely for expert members of the forum to contribute to the wiki. They'll know that their effort will pay off.

Recognize that many people have trouble culling the information they need from sources such as wikis and FAQs. Teach them how to do so. Newbies benefit from training in how to train themselves, and perhaps expert list members can even get training in how to train others.

Allow reputations to shine forth

Although reputation seems to offer a smaller incentive than many people expect in drawing forth contributions, it's potentially powerful. Something as simple as a sidebar showing the most prolific posters can encourage participation. A few people may try to abuse the system by flooding the forum with irrelevant or low-quality postings, but eventually they'll almost always get flamed off the list.

Rating systems are heavyweight solutions that require too much effort for most forums, but one could try more informal reputation-building systems such as regular "recognition days" where people explicitly thank particular people who helped them, or vote for a roster of helpful list members.

The tools available for organizing documentation are still in their infancy. The tools available for organizing people into online communities offer even more potential. Both can be put to use to improve the education of computer users and to expand their sharing of that education.

Thanks to Bill Lebow for his advice on statistics and data display, and to several others who gave advice on this article.

Related Articles

Andy Oram is an editor for O'Reilly Media, specializing in Linux and free software books, and a member of Computer Professionals for Social Responsibility. His web site is

Return to

Copyright © 2009 O'Reilly Media, Inc.