Anne Gentle vs JoAnn Hackos: Is There a Documentation Wiki In Your Future?

By Anne Gentle, special to TheContentWrangler.com

JoAnn Hackos’ recent article titled Is a Documentation Wiki in your Future? struck a chord with me because of my upcoming article about wikis for technical documentation in the September/October issue of STC’s Intercom. I know that many writers have wikis in their present and future. I have talked with people who have acquired a company with a wiki and had to figure out what to do with it in addition to the wiki they had already started. Merge the two? Maintain separate ones? I don’t know what they decided, but I do know this: wikis are not too far in the future for many of us, as this list shows—they are here now.

Because of my upcoming article and the research I’ve done on wikis over the past couple of years, I think that JoAnn’s article provides good information. JoAnn’s guidance has been valuable for all of us over the years. However, her wiki best-practice information is unfortunately buried under alarmist anecdotes that do not capture the spirit of wiki development that is already happening in corporations. I’d like to review the article here and offer commentary to help others get to the great conclusions at the end.

Nerd customer scenario
The initial scenario presented in JoAnn’s article, erasing rather than editing a wiki article, is considered an act of vandalism in nearly all wiki communities. Based on typical wiki use for software and hardware products, I’d say the scenario is unrealistic. Instead of the writer having to rewrite, the writer would have every right to re-establish his workflow article and clear out the customer’s replacement article, perhaps moving the customer’s article in a better location for troubleshooting the particular problem that the customer is trying to work around.

The HBS case
The Harvard Business School article that JoAnn links to describes one Harvard academician’s struggle to keep his article from being deleted by the “exclusionist” faction at Wikipedia. Read the article to the end, however, and it offers some great Q&A about corporate wikis. As for the Harvard professor, other people have noted that what happened to him was also an act of vandalism—it’s just that the vandalism was invoked by an administrator when he removed the article.

My fear is that many busy tech pubs managers are not going to scroll past the first screen of the article and, therefore, come to the completely wrong conclusion: “If JoAnn Hackos considers wikis to be risky and possibly a waste of an information developer’s time, then I should not encourage wiki building.” I believe this high-risk conclusion is the wrong message to get from the article.

Instead, the message I took away after reading the entire article, and the one I would hope other readers would take away, is this: users should be asked to contribute information that’s truly valuable and hard to get because it’s their perspective (use cases, scenarios), but users should be prevented from documenting workarounds in your wiki. In the rest of this article, I’d like to reinforce Joann’s suggestions for the types of content that work well in wikis and talk about the motivators for contributions to a wiki.

Advice about wikis and technical product documentation
If you read JoAnn’s article to the end, and think about it for a while, you can distill some practical advice. Following are my interpretations of that advice, taken from the article:

JoAnn suggests an excellent source of content—ask your users who have scenarios and use cases to write those up for the wiki. This nugget is an excellent idea. Your users have domain knowledge that is especially interesting and difficult to obtain. Also, think of expert users who are internal to your company, such as your consulting group. They will have excellent scenarios and use cases based on their client work. IBM is tapping this knowledge reserve with the RedBooks wiki. (I noticed it’s built on Confluence.)
Ensure that you are building an online community, not just writing for a wiki. I talk about this in my upcoming article for STC Intercom, in a special Web 2.0 issue.
I disagree with the implied connection between Wikipedia’s concerns and the concerns of a wiki for technical publications. I don’t think that tech writers should worry about Wikipedia and the elbowing that goes on behind the scenes there. The types of products we document, mostly software or application programming interfaces, simply do not have the political ramifications and motivations that are part of an encyclopedia’s maintenance. In the interviews and discussions I’ve had with people doing wikis, no one has cited actual malicious intent in any updates made to the pages.
For the most part, people who contribute to software or programming wikis are motivated by different factors than a typical Wikipedian. See Motivating contributions below.
Many of the people I talked with about using wikis for documenting their products noted a distinct connection between the customer support forums and the type of troubleshooting information found there and the wiki’s ability to “feel” like fresh content was a driving force.

Motivating contributions
From Peter Kollock’s article, The Economies of Online Cooperation: Gifts and Public Goods in Cyberspace, one can draw out four motivations for contributing. Apply these to your wikis and online communities, and find ways to encourage contributions:

Reciprocity: What will your customers receive in return for their contribution? Borrow a point system from your customer support forums, perhaps? Look to examples on developer networks where a correct answer or help contribution is rewarded with points that can be turned in for a t-shirt or conference registration.

Reputation: Will your customers appear expert in your product if they contribute to your wiki? This type of motivation is especially important to consultants. Make their contributions shine so that they will return with more scenarios.
Increased sense of efficacy: How will customers save time or money by contributing to your wiki? Consider a knowledgeable expert who feels she answers the same question via email over and over again. If she posts a thorough wiki article answering the question, she can create an email response template pointing to their wiki article.
Attachment to and need of a group: How will customers feel part of your team or part of your support team, if that motivates him or her? Think of the customer who proudly wears a slashdot t-shirt because he likes to feel part of a group. Tap that person as your group member as well.

So when should you look to Wikipedia for a model?
One of the reasons Wikipedia is successful is because it lands high on the search list when you search for a term. Your product documentation may or may not land high on the search list when you search for a relevant term. Simply putting the product doc in a wiki won’t necessarily increase your searchability and findability, but constantly updating your wiki will increase the findability of the site, and constant links to your wiki will also improve the search ratings on the site. It took Wikipedia six years to get where they are, and there aren’t always shortcuts.

Content leads the way
While I admire the intentions of JoAnn’s article, I fear that the reaction from the people who are reading only the first few page scrolls is going to be uncertainty and doubt regarding use of wikis for tech pubs. In response, I simply wanted to state that I haven’t found the initial scenario to be the case in all the discussions I’ve had. More often than not, the people I’m talking to would absolutely love to have interested “nerd” customers contributing at all. Instead of describing a scenario of us vs. them, we should try to figure out how to become part of the community and contribute repeatedly if we feel our contributions are worthy of our customers. In the Web 2.0 world, users should and can drive the content. Let’s be part of the solution, giving our customers the tools they need to both consume and contribute meaningful, useful content.

About the Author

Anne Gentle currently works as a senior technical writer at Advanced Solutions International, which provides management software for professional and social organizations such as the Society for Technical Communication, of which she is a senior member. She wrote a blog for her employer at BMC Software on talk.bmc.com since 2005, but has started writing new content for her blog, JustWriteClick.com. She has been a technical writer for over ten years, and has acquired many interests in that time, including structured authoring, social media, XML models for technical documentation such as DITA (Darwin Information Typing Architecture), blogging, wikis, online user assistance, and writing in an Agile development environment.