Friend or foe? Web 2.0 in technical communication

The rise of Web 2.0 technology provides a platform for user-generated content. Publishing is no longer restricted to a few technical writers—any user can now contribute information. But the information coming from users tends to be highly specific, whereas technical documentation is comprehensive but less specific. The two types of information can coexist and improve the overall user experience. User-generated content also offers an opportunity for technical writers to participate as “curators“—by evaluating and organizing the information provided by end users.

Technical writers are accustomed to being the gatekeepers for product information. They carefully organize product documentation, online help, and other user assistance for their readers. Compare this to the chaos of the Web, where content is splattered across blogs, forums, wikis, and the like with little or no organizational scheme.

And yet, readers are turning to the chaos of the Web for information rather than reading the online help. They begin with a Google search and work through the results until they find something relevant.

User-generated content and technical documentation can be complementary rather than competitive. In this white paper, we explore the implications of user-generated content and discuss how technical writers can integrate this content into their overall strategy.

NOTE:

The idea for this white paper was sparked by Andy Oram’s blog post, “What comes after the information age” on O’Reilly Radar (http://radar.oreilly.com/archives/2007/09/what-comes-after-the-informati.html). Tim O’Reilly comments on that post and raises the issue of content “curation.” Scriptorium’s initial response to the article is found in a Palimpsest blog post, “The Age of…Expertise?” (https://scriptorium.com/palimpsest/2007/09/age-of-expertise.html).

Cardinality in communication

The term cardinality is typically used in data modeling. It refers to the relationship between two objects and how they are connected. For example, a person should have a one-to-one relationship with a tax ID number (such as the U.S. Social Security number). But a person could have a one-to-many relationship with a phone number object (one person can have many phone numbers). The basic cardinality types are one-to-one, one-to-many, many-to-one, and many-to-many.

We can apply cardinality to verbal communication:

• One-to-one: A conversation between two people.
• One-to-many: A professor giving a lecture to a hall full of students.
• Many-to-one: A jury giving their verdict to a defendant.
• Many-to-many: A group of people at a party, all talking simultaneously at the top of their lungs.

For written and technical communication, cardinality is more complex.

One-to-one

In technical communication, the most common example of one-to-one cardinality is phone-based technical support. The end user talks directly to a company support representative. One-to-one communication is usually quite effective—if something doesn’t make sense at first, you can ask questions to clarify—but it is also expensive.

Figure 1: Phone-based technical support is one-to-one communication. Click on the play button to view animation.

One-to-many

Traditional publishing, including technical communication and user assistance, offer one-to-many communication. An author writes content that is consumed by many readers. One-to-many communication is much more cost-effective than one-to-one communication, but when writing for a large audience, authors necessarily create information that’s more generic than a person-to-person conversation.

Figure 2: Technical communication is one-to-many communication

There are several ways of defining Web 2.0, but for technical communicators, the critical issue is that Web 2.0 shifts communication from one-to-many cardinality into many-to-one and many-to-many. The publishing channel is no longer restricted to professional authors; instead, anyone can provide information to anyone else.

Many-to-one

Many-to-one communication means that multiple people are providing answers to a single person. For example, Person A posts a question on a mailing list and receives offlist responses from a dozen people.

Figure 3: Many-to-one communication involves multiple people providing information to a single person

Many-to-one communication is arguably the least efficient method of communication because of the overlap in effort to provide answers to a single person. However, for the person receiving the information, it’s often the fastest and the highest-quality communication channel. When several people provide answers, a consensus often emerges for the recipient.

Many-to-many

Many-to-many communication is at the center of the Web 2.0 concept. Everyone is requesting and receiving information, and roles shift fluidly from information provider to information recipient.

Figure 4: In many-to-many communication, the distinction between information producers and information consumers disappears.

User assistance in a Web 2.0 world

The content produced by corporate technical communicators is usually included with the product—as a printed manual in the product box or as online help accessible from the software’s menu. In the past, third-party information was available, but often difficult and expensive to access. For instance, many trade computer books are available, but they are not included with the product—a reader must purchase a third-party book separately.

Today, the privileged position of official technical documentation is eroding—users who are having a problem with their product often start by typing a query into Google instead of reaching for the manual or clicking on the help. In effect, professional technical communications are competing for attention with the collective intelligence of the web.

For many writers, this feels uncomfortable and vaguely insulting. As professionals, they feel that their efforts should be respected more than those of someone hiding behind a user name, such as JoeProductHater. In reality, however, technical writers are often constrained by corporate realities—they must be tactful about a product’s limitations. By contrast, forum participants have few or no inhibitions about criticizing products or suggesting alternatives.

Several components of the web and of Web 2.0 contribute to the user-generated content revolution.

Search

Most books and online help provide tables of contents, indexes, and (online) full-text search. But to use these search features, the information seeker must already be using that book or help system.

Today, it’s quite common to begin searching for information by simply typing a few words into a browser search box.

Figure 5: Is your user assistance content exposed to search engines for indexing?

If you want people to find and use your content, you must:

• Publish in a location that is accessible for search engine indexing
• Create content and keywords that appear in the results of a search
• Provide useful, accurate information

Many technical writers are concentrating on the last item and ignoring the first two. But if nobody is finding their content, then it might as well not exist. Unfortunately, many writers see this list as a list of exclusive choices—they ask whether they should optimize keywords instead of ensuring that documents are technically accurate. The answer is that they must do both.

Figure 6: How do I get to be first? (Google search results from April 1, 2008; http://www.google.com/search?q=user+assistance+web+2.0)

One significant challenge in search technology is to create a universal search that works across the web, online help, forums, and so on. Most message board software provides search functionality, but that search probably works differently from the typical web-based search. The search features built into web-based help systems likely use a third search algorithm. For a company that provides multiple types of information on their web site, this presents a serious dilemma. How should they aggregate and present search results from three (or more) different engines in a unified whole?

Each of the available options has limitations:

• Group search results by location. This is technically the easiest solution. Forum results go in one list, user assistance results in another list, knowledge base search results are in a third list. But from a searcher’s point of view, it’s pretty unfriendly.
• Ladder search results into a unified presentation. All of the #1 search results are presented, followed by all of the #2 search results, and so on. The problem with this approach is that if the relevant search results are concentrated in one type of result (for example, the user assistance results are much better than the forum results), the searcher is presented with information that’s positioned higher in the list than it should be.

The “correct” solution is to use a single search technology across all of the different types of content, but this may not be feasible due to technical limitations.

Blogs

Blogs are usually colorful and often insulting. Bloggers operate with little or no sympathy for the realities that drive corporate decision-making. Instead, they skewer products (and sometimes documentation) mercilessly.

Figure 7: Bloggers are often not nice (web site captured on April 8, 2008, http://monkeypi.net/?p=133)

For technical communicators, blogs open up several opportunities. First, the criticism that bloggers can be valuable ammunition in improving products. Technical writers are often stymied when they request product improvements based on issues that occurred while writing product documentation. A blogger’s impolite—and public—dissection of the deficiency may be just what’s needed to move the issue up the priority list.

When a blogger complains about being unable to use a particular feature, is that a product deficiency or a problem with the documentation? Technical writers can use blog postings to identify places where user assistance should be improved.

Finally, and most controversially, technical writers and others can participate in blogging. One option is to comment on a blog entry. For example, if a blogger complains about a particular feature, the technical writer could provide a link to the online user assistance and request feedback on whether the instructions provided there are useful.

The most engaged (and terrifying) option would be for the technical writing group to start their own public blog to spark discussion with their readers.

NOTE:

All of these approaches may be constrained by corporate policies, which should be thoroughly investigated first.

Blog comments for user assistance

A few companies, notably Adobe, allow readers to comment directly on their user assistance. Adobe’s LiveDocs interface provides an Add Comment button at the bottom of each help topic. They also provide an easy way to generate a list of all comments for a particular product.

Figure 8: Adobe LiveDocs allows reader comments (web site captured April 8, 2008; http://livedocs.adobe.com/air/1/airextflash/)

This presents some really interesting conundrums, like “Who owns the information?” and “What should you do about inaccurate comments?”

Adobe’s user assistance is available on the Web to the general public. To add a comment, however, a reader must log in with an Adobe ID. Therefore, Adobe can associate comments with a unique email address. Although it’s obviously quite easy to set up multiple email accounts, this approach does presumably make readers think twice before posting something completely inappropriate.

Permitting readers to comment on your content is an interesting idea. It should help to:

• Identify areas where documents are inaccurate, confusing, or incomplete
• Identify areas that are controversial (where a lot of comments tend to accrue)
• Provide a venue for readers to participate in a (somewhat) controlled environment

It does present another interesting problem. If a commenter identifies a problem and the technical writer makes the needed updates and republishes the information, what should happen to the comment? Should it be deleted because it is no longer relevant? What if the comment is inaccurate? Should the comment be deleted in that case? Should the person deleting the comment explain why it is being deleted? Or should all comments be preserved permanently?

Forums

Online forums predate Web technology; some may remember the old CompuServe bulletin boards. Today’s web-based message boards provide a gathering spot for people to discuss particular products, games, or common interests.

Broadly, forums can be divided into “corporate” and “third-party” boards. That is, some companies provide forums for their own products and host the forums on their own web sites. But forums are easy to set up, and many forums exist independent of corporate control. For example, flyertalk.com provides a huge set of message board for frequent flyers with discussions of specific cities, frequent flyer programs, travel security, and much more. The discussions are often raucous, and the U.S. Transportation Security Administration is a particularly popular target. If you fly frequently, this web site provides invaluable resources, tip, tricks, and workarounds for making travel bearable.

Companies may want to control the discussion on corporate forums, but if forums are too heavily moderated, participants will migrate to another, less restrictive discussion option.

Figure 9: Frequent-flyer forums for every imaginable program, definitely not endorsed by the airlines (web site captured April 8, 2008; http://flyertalk.com/forum/forumdisplay.php?f=374)

Wikis

The largest and most well-known example of a wiki is Wikipedia (www.wikipedia.com). A wiki enables participants to author content collaboratively.

At its best, a wiki results in articles that capture the collective intelligence of the participants. In some cases, though, disagreements can escalate into article vandalism and other problems. In a wiki, participant A writes an article, participant B rewrites the article, and participant A gets very upset. People have a visceral reaction when their writing is changed.

Wikis are extremely useful for developing content that benefits from consensus. They are used heavily by gamers (perhaps because game designers tend to provide minimal documentation?). The World of Warcraft wiki, for example, is enormous.

Figure 10: Wiki navigation helps make information easier to find (web site captured April 8, 2008; http://www.wowwiki.com/Portal:Main)

Wiki users can organize wikis content into logical groupings. These classifications can then be used to support navigational aids. By contrast, forums usually provide only very broad search categories.

Evaluating credibility

Technical writers have a built-in advantage in credibility. Their work ships with the product— on a CD, as a paper manual, or as user assistance that’s connected directly to a software product. Readers assume that officially provided technical content has undergone some sort of quality control. (Although a company’s reputation for technical documentation quality may increase or decrease readers’ trust in the content.)

For user-generated content, there are some qualitative criteria that readers use to evaluate whether a source is credible. These include the following:

• Anonymity. A blogger whose identity is known is generally more credible than an anonymous blogger. However, like anonymous sources in journalism, blogging anonymously could actually increase credibility if the blogger has an excellent reason for remaining unnamed. For example, the blogger known as Mini-Microsoft (http://minimsft.blogspot.com/) is thought to work inside Microsoft, but his (or her) blog clearly does not toe the corporate line. In this case, anonymity makes the postings more compelling because we believe that Mini-Microsoft probably does have inside information which necessitates his or her anonymity.
• Post count. Most forums provide this information. Every time a poster publishes a message, the post count increases. Although by itself post count does not equal credibility, a higher post count indicates longer participation on the forum and greater investment in the topic at hand.
• Membership date. Mainly used in forums, a membership date lets you evaluate how long that person has been participating (under that ID) in the forums. Long-time participation, especially combined with regular posting, increases credibility.
• Member types. A general member might be someone who just joined and has fewer than 100 posts. A senior member might have at least six months on a forum and more than 100 posts. Moderators and administrators are connected to the forum management. Many corporate forums also identify participants who belong to the host company with their own membership categories. Finally, you see special member types, such as the Microsoft MVP or the Adobe Community Expert, that indicate people who have been recognized by the host company.

Figure 11: A Microsoft MVP identifier (web site captured April 8, 2008; http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=947210&SiteID=1)

• Badges. A badge provides graphic shorthand for that participant’s level of seniority on the message board. For example, a technical support person from the host company might have one type of badge and a senior (external) member a different type.
• Ratings. Ratings are relatively new. In some forums, readers can vote on the usefulness of a particular contribution. Articles that get a lot of votes are highlighted in search results and elsewhere. Based on votes on the forum posts, a particular author might then also have a rating for providing especially useful or useless information.

Taken together, these items give readers a way to evaluate the reliability of a message.

Advantages and disadvantages of Web 2.0 content

User-generated content tends toward the following characteristics:

• Authentic. The people contributing content are rarely tactful; their opinions probably don’t reflect official corporate positioning. The fact that information is unfiltered is one of its greatest assets to other readers.
• Passionate. It takes motivation to write a blog post, participate on a forum, or edit a wiki page. The people creating Web 2.0 content are passionate about the products they are writing about. Apathetic people don’t bother to contribute.
• Specific. User-generated content tends to be about one person’s experience rather than the general workings on the product, so it tends to be quite specialized. For example, a discussion of a database installation probably would describe how to configure a specific version (the one the author used) and not how to install, in general, any database. If the configuration being described matches your particular requirements, this could be a good thing.
• Not comprehensive. User-generated content will cover the information that users find -interesting or compelling, unlike technical documentation, which is expected to provide universal coverage of the product. User-generated content will go much deeper than technical documentation in places, but it will also have enormous gaps in coverage.
• Not edited. With the possible exception of content in very large wikis, user-generated content is not edited. The quality of the writing will be as good as the effort that the original author put into the message.
• Not curated. Users write about what they care about. Important but boring topics may not get much attention. Ratings and other voting mechanisms can help surface content from the ocean of information, but useful information may sink into oblivion because it is not linked or sufficiently searchable.

Where professional technical communicators are most valuable

Professional content creators add the most value where content curating is needed:

• Conceptual information and product overviews. A high-level description of a product requires time and attention from someone who understands the entire product. For complex products, discussions of the best implementation approach could be invaluable. Most user-generated content will focus on specific tasks that need to be completed rather than on providing perspective.
• Thorough coverage of all topics. Instead of focusing on interesting and exciting subject matter exclusively, a professional content creator will ensure that all of the needed topics are discussed in the documentation and user assistance.
• High production values. The professionals win on quality—user-generated content is rarely edited, copyfitted, or even designed.
• High-stakes documentation. If documenting by trial and error is out of the question, the professionals are necessary. Some obvious industries where “let the users figure it out” is probably not a very good idea include aerospace, defense, and medical devices.

Where users are most valuable

Users can (and will) play an important part in many industries where their participation is less risky. They are especially good at the following:

• Providing technical support and workarounds
• Correcting errors in the official content
• Highlighting things that are not working
• Demanding changes where they are needed

Figure 12: User-generated content and professional content tend to occur in different areas

Technical Writing 2.0

Given the impending collision of technical writing and Web 2.0, what will Technical Writing 2.0 look like for professional content creators? Any strategy must take into account corporate policies (if they exist), but consider the following actions:

• Read blogs, forums, and wikis to keep up with user comments.
• Correct mistakes when you find them by commenting on blogs and forums or editing wiki pages. (Note that some wiki policies discourage editors who have an affiliation with the topic in question from making changes. Be sure that you understand the wiki’s culture before you make changes.)
• When you participate in online discussions, be clear about your corporate affiliation. You might choose not to give your entire name, but you could create an ID such as ProductXTechWriter that explains your position.
• Your power as a gatekeeper is greatly reduced. Although you can choose to omit information from the official product documentation, it’s likely that the information will surface somewhere on the web. Instead, embrace your new role as a curator whose job it is to ensure that the best, most useful information is highlighted for readers. For this, product expertise is critical.
• Be cautious about product positioning or marketing content. If the official documentation glosses over problems, readers will probably choose unofficial, unapproved alternatives. It’s not necessary for the official documentation to bash the product, but a dose of candor will help you keep your readers.

Integrating Web 2.0 and user assistance

Just as the availability of online help and printed technical manuals required a new approach to technical communication, the rise of Web 2.0 technology means that technical communicators need to assess content development strategies. We recommend the following for products whose use does not have life-or-death consequences:

• Corporate technical content should provide comprehensive coverage of basic concepts with a particular focus on supplying conceptual information.
• The product web site should provide a platform for customer-generated content with user forums, wikis, and the like. The platform should include rating mechanisms (article ratings, voting, badges) to help readers evaluate the credibility of contributors.
• Top contributors should be recognized, both online (badges) and with token gifts (shirts, key chains, and other swag).
• The product web site should include a blogging platform for corporate bloggers.
• The product web site should provide links across the various content types to help readers locate related information.
• The product web site should provide integrated search across the various content types.

For professional authors, it’s tempting to ignore user-generated content and hope that it’s a fleeting fad. This is, however, highly unlikely. Motivated users will always find a way to get their message out, and Web 2.0 technology makes it easy.