oreilly.comSafari Books Online.Conferences.


Rethinking Community Documentation

by Andy Oram

A new era is halfway here, and nobody has recognized its impact--even though we've all participated eagerly in its arrival. The way we educate ourselves to use and program computers is shifting along many of the same historic lines as journalism, scientific publication, and other information-rich fields. Researchers have pounced on those other trends, but computer education remains short on commentary.

People say casually, "I find my information about using computers by searching online," but few have asked how that information gets online, or how it changes the way they use their computers. It's delightful to see thousands of ordinary people writing up guidelines to help each other; the outpouring of energy is impressive. In the week this article was written, when Microsoft--the most resource-rich software development center in the world--announced the MSDN wiki for community contributions, and eBay creates its own eBay wiki, you can tell the movement has taken root. Yet before it goes much further, the public should explore some key questions:

  • Why are people writing this information?
  • Is the information organized and made available in the most effective manner?
  • How can readers separate good advice from bad?
  • Are readers able to imbibe general knowledge from these quick fixes and solve related problems later?
  • How can authors be rewarded so that they spend even more time generating useful information?

I care about community documentation for several reasons. First, as a heavy user of many computer technologies (with a focus on free and open source software), I benefit personally from amateur online sources. Second, I'm intrigued by the culture of mutual aid this movement reveals, and its meaning for the democratic sharing of information. Most imperatively, this movement cuts into my living as an editor of conventional documentation, for several reasons I desperately need to understand.

Community documentation has swept up so many talented people and accomplished so much that I've decided to join in and help it flourish. The topics I'll cover in this article are:

A Definition

I use the term community documentation for anything generated by developers and users (mostly amateurs in the field of writing) that helps people use their systems. The documentation could be as small as a question and an answer on a mailing list. As people answer more questions, some write up their answers in a more formal way and post them as web pages. Wikis are a further development. Zealous technology fans have written and released several complete how-to books.

Much of this documentation is:

No published book could keep up with the evolution of software, particularly software distributed over the Internet. In fact, many important developments become old hat before a book or magazine publisher could even solicit and publish an article on them. This is why wikis are popular; they can tack and turn along with the software.
Information emerges on mailing lists bit by bit as a newbie poses a problem, experienced users toss back suggestions or questions for further research, and the truth of the situation comes into focus. The process can be exciting to watch, like a puzzle everyone is competing to solve. Interactivity is not limited to discussion forums; even a relatively fixed piece of community documentation (such as an online tutorial) has probably undergone rounds of review and comment.
While closed forums provide valuable and safe places for some kinds of discussions, this article covers the documentation on mailing lists and web sites that anyone in the world can view. This openness is central to the culture and ecology of community documentation, because when you recommend some reading to a correspondent, you don't want to worry whether he can't get access to (or can't afford) the document. That is sometimes the case with printed materials.
A posting to mailing list may concern a particular bug in a particular release of software, or a problem unique to one person setting up an unusual environment. However, not all community documentation is like this; extensive essays on stable topics also turn up.

These four criteria are not unique to information about computer technology. I described the same four criteria over four years ago in an article proposing new online media. I wrote that article as a bystander, thinking it referred to pop culture. I didn't think I would be anticipating the field I myself would have to work in.

Why the Shift to Community Documentation?

People have been asking friends for help ever since the discovery of language. In a more recent development, mailing lists started in the early days of computer networking. The Linux Documentation Project--completely volunteer-run--goes back to 1992, practically as far as Linux itself.

Community documentation has increased its hold on computer education over the last few years. Traditional book sales and training courses have stayed robust in some areas of technology, but a noticeable amount of learning has gone online.

The reasons for this change rest on several levels: technology, motivations, and social attitudes.


Technological changes affecting documentation include:

Improved search capabilities
Lots of good information (and bad information, too) is buried in three-month-old archives or other obscure sites; modern search engines can turn up quite a bit of it.
Improved network connections
When you're always online, the temptation is overwhelming to slide over to that little Google window in your browser and type in a few words. I did it a dozen times while writing this article.
Improved authoring tools
The inventions of the blog and the wiki were modest technological tweaks to web technology, but had a huge qualitative effect in bringing down barriers to grassroots communication.
Improved research opportunities
Free software opens up every aspect of a system to examination by anyone with modest computing skills. Even proprietary systems and systems involving hardware come with more information today; vendor attitudes are also more open to sharing ideas.

Technological phenomena create an environment where community documentation can flourish, but each person must have an individual reason for contributing to the documentation.


The motivations for doing community documentation are well worth some formal research. This research would parallel the extensive research into why free software developers give away their work. For free software, there are several trends. Often, the software developer is simply sharing what he needed to write for purposes of his own. As Tim O'Reilly has pointed out, the situation is not so simple for free documentation: authors don't benefit from it directly, but must have reasons to generate it for other people.

Anecdotal evidence suggests reasons people write community documentation:

Informal support
Many developers or other members of software projects go on the online forums to offer technical support, which in turn promotes use of the software.
Mutual aid
People help others with the expectation they themselves will get help when they need it.
Closely related to mutual aid, people say, "I received help when I was new to this technology, so I want to help others."
Reputation building
Consultants, trainers, job-seekers, authors, and others hoping to build a career go online hoping for recognition and respect.
Personal growth
By offering advice to others and by tracking them through the process of repairing a problem, advisers build their own diagnostic and communication skills.
Mixed in among the free documentation are sites with advertising. Some of these sites draw enough traffic to make a modest but noteworthy income for their authors.

We should look past these immediate motivations. Something much bigger is going on, and it's particularly important to traditional publishing--a change in social attitudes.

Social Attitudes

It's not surprising that authors face a choice between participating on the Internet and writing for traditional books and magazines. The most successful authors find time for all of these media. When they do choose between them, books increasingly lose to the competition. Something about books suggests a bygone era.

Perhaps in this age of wikis and instant communication through online chat, people don't want to wait nine months to write and release a book. Yet even that doesn't explain the shift. More fundamentally, in our day and age, connections with other people have taken precedence over book publishing.

Taking nine months to write and publish a book is more than information sharing; it's self-expression. Nowadays, this degree of self-expression can seem like self-indulgence.

Our sense of individual identity urges us to self-expression. Back in the 1950s and 1960s, the search for identity became a central concern for millions of people. Social commentaries of all sorts quoted such psychoanalysts as Erik Erikson, who wrote books with the titles Identity: Youth and Crisis and Identity and the Life Cycle, and who defined the early stages of life as the search for individual identity. (Erikson said, however, that one must move beyond one's "identity"--the collection of one's social traits--in order to truly be oneself.)

Now we live in a world of over six billion people, heading toward nine billion. In such a world, are you really so important? The search for an individual identity just doesn't seem to make that much of a difference.

Meanwhile, the Internet connects us with millions of people, offering instant gratification when we share an idea quickly. Reciprocal interaction and the co-development of ideas, in my opinion, give a lot of people more satisfaction now than the self-indulgence that comes from writing a book.

Regardless of whether you accept my sociological explanation of the move to community documentation, consider the problems that it brings.

Pages: 1, 2, 3

Next Pagearrow

Sponsored by: