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

By Anne Gentle, special to

image 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

image 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 since 2005, but has started writing new content for her blog, 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.

Tags: , , ,

7 Responses to “Anne Gentle vs JoAnn Hackos: Is There a Documentation Wiki In Your Future?”

  1. danortega September 5, 2007 at 5:15 pm #

    We’ve been looking at the integration of wikis into our content management workflow as part of a longer term expansion of our system to include rich media. The intent of the wikis is to allow subject matter experts to contribute specific elements of information, but subject to the approval of the originating author. The example would be field service personell who are working on complex machinery that requires extensive documentation support. It is likely they will discover better/faster ways to service the machine in question than what is specified in the user documentation. This type of input, routed to the document author (or authors) subject to their approval prior to posting, would expand the feedback loop to potentially hundreds or thousands of SEMs. A wiki in an enterprise environment will look very different from wikipedia, which is very consumer oriented. As long as the proper controls are in place, there is no need to fear the wiki, and enterprises (at least our customers) are very control-oriented, as they should be.

  2. Stewart Mader September 6, 2007 at 10:38 am #

    Wow, this is an excellent post Anne. Just the kind of reasoned thinking that should take place when thinking about how to use a wiki within an organization.

    Regarding the Harvard prof and his struggle to keep an article from being deleted from Wikipedia, that’s not an example I would have used as JoAnn did because what happens on Wikipedia is quite different from what happens on an organization’s wiki. Deletion on Wikipedia sometimes comes across as a personal affront to people, and I think it’s because their motivation for being on Wikipedia is ego-driven. Deletion of content in an organization’s wiki might just need to happen sometimes, and if a wiki is being used in a truly collaborative way, deciding the delete or change content should be a mutual decision largely free of personal motivation.

    Great point on customers and the Us. vs. Them mentality too – that mentality shouldn’t exist anymore, in my opinion. With social media and the focus on building communities around products, projects, services, etc. I think that there shouldn’t be “sides” anymore – in fact, there really can’t be in a healthy community. Disagreement and debate, yes, but sides, no. They’re just not needed to hide behind when people are working together.

  3. Steve Manning September 7, 2007 at 8:31 am #

    While JoAnn’s opening scenario is a little apocalyptic, it is a point well made.  On the internet, access without control leads to chaos.  It is something that internet users have wrestled with for a long time. 

    There have always been mechanisms on the internet for communication and collaboration, from usenet news to listservs to wikis.  Where there are moderators, whether corporate or volunteer, you have a much greater chance of having effective communication.  Without, you get flame wars and arguments and a whole lotta useless noise. 

    Dan’s comment, I think, says it best:  “As long as the proper controls are in place, there is no need to fear the wiki …”

  4. Amanda_Cross September 8, 2007 at 11:30 pm #

    I faced this exact “us vs them” attitude when I suggested a user community, featuring a wiki, at my last job. The director of marketing, who probably was not the ideal guy to put in charge of my contribution to the Suggestion Box, didn’t want to give customers a venue to complain about the product.

    The fact that there are already limitless online venues for customers to complain about the product hadn’t occurred to him. Better to be part of the conversation, I argued, to remove wanton bashing, respond to criticism, and maybe even correct the problems the customers have problems with (imagine!).

    The marketing director put the work back on me, and I ended up leaving the company for unrelated reasons, so it will go nowhere. In my new company, I’ve heard rumors of a starting up a wiki, and I’m hoping to get in the development. I wonder what capabilities are out there for incorporating XML-based documentation with wiki software. Anyone done a thing like that?

  5. annegentle September 10, 2007 at 11:12 pm #

    Thanks, great comments, all.

    danortega – Great idea of using content from field personel where time is essential yet you want to filter the content before posting. A former manager of mine noted that there are certainly examples when an early product or service design is not quite cooked and you wouldn’t necessarily want to air your company’s dirty laundry if there was an embarrassing workaround due to a design flaw. But in a really open culture your customers would prefer that you just admit there’s an issue and you’re working beside them to make it right.

    Stewart – Yep, Wikipedia gets some emotional responses out of people, doesn’t it? How about a humorous one – off of Darren Barefoot’s Google Reader feed: Ha. I hope in the next year or two we find other better wiki examples to draw experience from, because Wikipedia comes with some political and pop culture baggage that most technical publications don’t or won’t carry.

    Steve – I had a great conversation offline as a result of this post, describing a flame war in a gaming online community resulting from the lack of moderation and lack of arbitration and general hands-off attitude of the wiki owners, and resulting in a lack of trust in the wiki and forum content itself with one contibutor walking away and never looking back. So there are certainly near-apocalyptic (to the person experiencing it at the time anyway) scenarios that occur and have happened for years – this particular conversation was with someone who had been editing and contributing to wikis for literally years. I’m going to keep an eye on the people with the wiki stories from “two years ago” – my guess so far is that their stories are that moderation and arbitration are essential for the community to trust the content.

    Amanda – wow, I have a blog post waiting in the wings on this very topic – using blogs to respond to other blogs’ criticism of your product or company.

    I, too, am very interested in how DITA or XML-based documentation can be used to create wikis. Closing the single-source loop is the question – how will you incorporate others’ contributions? Instead of being writers we could be editors much like the magazines and newspaper old media model, where we choose what content has the right voice and message and therefore stays as (or becomes) XML source. Or, make certain contributor’s view of the wiki XML editor the most limited (like the MSDN wiki did, it only allowed three types of content/elements from contributors) but give your power contributors the most XML- or DITA-like interface for inputting content. A three-field web form for casual contributors, and the DITA Storm editor for company contributors perhaps? An Intel writer proposed that to me via email a few weeks back, and it’s a great concept.

    The more I write about the topic of wikis for technical publications, the more I learn and mold my thoughts and ideas. Thanks you all for contributing to this post with your excellent commentary and feedback.

  6. Charles Jeter September 22, 2007 at 12:35 am #

    Wonderful article, Anne. I also looked at the same wikipedia Harvard article in my blog post:

    Amanda / Anne – I’m supposed to be reviewing an XML-based authoring tool this month which has Web 2.0 features including comments and feedback. My post above details a bit more about it, and if you happen to have any questions or desires about how this wiki interfacing XML tool would function, please let me know so I can include them in my interview with the development team.

    It might be closer than any of us realize, particularly if the content can be easily repurposed with a custom schema!

    My stipulation in my wiki corporate usage post is that internal rivalry remains the top killer of corporate thought. A successful corporate wiki could really depend on the corporate environment being open enough in the first place to support free thinking, because providing a wiki in a dysfunctional corporate environment would be devastating.

    Giving thought to what you have said in your article, you have points that directly point to some sort of crossover knowledge resource / technical communicator who would be able to handle the wiki and shape the knowledge on a regular basis. I would wonder if that would fall into the Tech Writer position, the Tech Support position, the Project Manager, or Marketing. Of course in a perfect world all would work equally to help support, but someone has to steer the ship.

    The part of your post I still need to give thought to is exactly what you postulate in your comment regarding closing the single-source loop. It’s more of a question about how to format that content and properly credit the customer while still editing the content for readability and technical accuracy.

    I’ve been concentrating on discussion and workflow for content behind the firewall, but I will be providing a Wikipedia part 2 quoting your article because you completely cover ‘beyond the firewall’ – an area I did not cover because of the general resistance I’d seen.

    In particular, you optimistically cover the number one objection I’ve heard, which is the skepticism by marketing about how customers may flame the product on their own site.

    I’m writing a post on Web 2.0 Tech Support this week which follows the concept of enabling technical support engineers to post online and in blogs to counter the flames before they become out of control.



  7. Anne Gentle September 25, 2007 at 10:55 am #

    Charles – I’m trying madly to get a reasoned response to your comment, but just haven’t pulled all my thoughts together yet, and I couldn’t find an email address for you. So this will have to do.

    I have been enjoying reading your blog, and I am definitely interested in the XML-based authoring tool that has Web 2.0 features including comments and feedback. Do you use it to author online help or user assistance?

    Dee Elling said that she thinks comments are a great start to generating online community response in an interview I had with her earlier this year (see so for many companies a built-in comment system would be a great leaping off-point for social media while not having all the initial concerns about a full-on wiki. And it appears that the MSDN wiki stepped towards comments rather than towards full edits of content. So that is an interesting trend to note.

    I’ve added your RSS feed to my feedreader and look forward to reading more. Thanks!

Subscribe To Our Newsletter

Join our mailing list to receive the latest news and updates from our team.

You have Successfully Subscribed!