Table of contents

Abstract

Cardinality in communication

User assistance in a Web 2.0 world

Technical Writing 2.0

Integrating Web 2.0 and user assistance

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.

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.

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.

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.

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.

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.

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.

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.

• 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

Next page:
Technical Writing 2.0

Copyright © 2008 Scriptorium Publishing Services, Inc. All rights reserved.