Wikis in Documentation: Ann Gentle Asks, Can Wikis Stand Alone, or Must They Be Supplements?

by Tom Johnson on Jun 26, 2007
categories: technical-writing • wikis

Ann Gentle of BMC has been researching the use of wikis in documentation. Although wikis have been around for at least ten years, they are finally getting more attention. Ann writes,

It's funny, in an early blog post I wrote on the internal blogs at BMC I said that I did not see how wikis would be used successfully for technical publications. I have since changed my once low opinion of wikis but I still see them supplementing other documentation, not substituting completely for technical documentation. I'd welcome discussion about wiki as standalone or supplemental end-user documentation. What do you think? Should the merits of wiki for certain products win out as the exact right documentation for that particular product especially one either related to an Agile methodology or social media? Or are wikis relegated to an upgrade to the customer support forum with a kludgy way of entering the information and no good method for outputting an information deliverable worth reading?

My Response

Lately I've had the opportunity to delve into SharePoint 2007, exploring its wiki, blog, and RSS functionality in depth. I'm convinced that SharePoint 2007 is the tool that's going to change the way enterprises view wikis. Right now wikis are mostly web tools popular among open source projects where remotely located project members contribute to the documentation. SharePoint 2007 provides the same wiki functionality wrapped into the secure SharePoint tool that corporations love.

Top Reasons Why Wikis Will Increase in Popularity

I'm not an expert on wikis, but so far this is what I've noticed using the SharePoint 2007 wiki:

1. Wikis are fast. This is literally what wiki means in Hawaiian. I think I can complete a documentation project in two-thirds the time using a wiki instead of a traditional help authoring tool.
2. Wikis change the perception of help. Let's face it: online help has a bad reputation of being useless. Wikis provide a new format that can counter that perception and empower critics with the responsibility to act on their jabs.
3. Wikis draw upon collective intelligence. Even if you only have a handful of contributors to the wiki, drawing upon collective intelligence from actual product users is invaluable. Just getting one edit can expand the usefulness of your documentation tenfold.
4. Wikis are convenient. With wikis, you don't need to attach files to emails, compile an online help file, transfer folders to a shared server, decipher edits on paper, or try to interpret Word's track changes. Editing of the files by SMEs and editors is a cinch.
5. Wikis give the impression of being up to date. Even if they aren't, wikis have more life. You can update them on the fly. One minor update to a page can renew the user's faith that the documentation is current.
6. Wikis have tremendous potential in the enterprise. Think about all the documents that project members collaborate on in the enterprise. Wikis will make project teams much more efficient (and fun).
7. Wikis are a curiosity that merits experimentation. Everyone I meet is curious about wikis. They look at them with a new-found wonder. That's worth something.

Challenges with Wikis

I see several challenges that wikis pose:

• Most users don't have the mindset that they can contribute.
• Wikis have limited single-sourcing ability (at least SharePoint's wiki does).
• If you correct or eliminate a user's update, you might offend that user.
• Simultaneous edits cause problems when saving the material.
• Wiki tools are still fairly primitive.

SharePoint 2007's Wiki Strength

Unique to the SharePoint wikis is the ability to create additional columns/fields for each wiki page. For example, you can create an additional column called Category and force the user to select one of a dozen categories from a drop-down box. You can also add a field that forces the reader to answer yes or no to the question, "Does this page need more work?"

You can then create custom views that sort the wiki pages by the custom columns you created. This ability to add your own custom metadata to wiki pages, and then sort by those metadata fields, provides a lot of flexiblity and power. It alleviates some of the strained organizational limitations wikis have, and allows you to provide information to users in a variety of navigational assortments.

Wikis are notorious for being scattered mazes of chaos. But if you embed the right metadata tags from the start, you can create enough views for a variety of perspectives to satisfy users.

Ann Gentle Podcast Recommendation

By the way, several months ago I listened to an excellent podcast by Ann Gentle called Exploring Information Technology. I kept meaning to post about it, but never did. I really enjoyed it, Ann. I hadn't run across your name before. Thanks for linking to me -- that's how I discovered your (non-work) blog.

Other Wiki Resources

Just thought I'd throw in a few more wiki resources:

• Online Community Report: When to Use a Wiki
• I also did an in-depth podcast with Katriel Reichman on Tech Writer Voices a couple of months ago.
• Installing Mediawiki
• Installing Dokuwiki