Using Wikis as Project Documentation Tools

by Tom Johnson on Feb 3, 2007
categories: technical-writing • wikis

I was talking to Charles Arnold after the last STC-Suncoast chapter meeting about using wikis as project documentation tools. Neil Perlin just presented on Web 2.0, and referenced James Surowiecki's The Wisdom of Crowds: Why the Many Are Smarter Than the Few and How Collective Wisdom Shapes Business, Economies, Societies and Nations. Surowiecki's main idea is that collective wisdom almost always outstrips individual wisdom.

I was thinking about this today as I continued documenting our customized version of CRM, a client relationship management application from Microsoft. The IT team implementing it consists of about 30 people. Several SMEs know the product backwards and forwards. There's a training department that is leading several sessions on it, and a support center with some sharp troubleshooters who also know the product well. Then there are business liaisons who know the business side of the application — the contextual, real-life angle of how users would actually use the application.

However, none of these groups is writing the user documentation. Instead, I am. I happen to be writing all of it, too. If I am lucky, one of the SMEs will briefly review the user help before it's published to the users. But to think that I can suck in all the knowledge that is floating around in the minds of the project team, and compile/arrange/present that without dedicating almost all my time as a field reporter, is just naive.

The model of one writer or even several writers tackling all of the documentation is a model that will soon be history as Web 2.0 trends take over in technical communication. Wouldn't it be so much cooler if we could have a wiki that I could work off of, and which everyone could read, review, edit, and even contribute towards? I could draw upon the collective intelligence of the entire project team, rather than just my own fiddlings and guesses with the program.

I was playing around with the SharePoint 2007 wiki features and also those of Socialtext. Here are the barriers I'm up against:

• Wiki wysiwig's are primitive (technical documentation can have some complicated styles, with several levels of lists).
• Once all the info is in the wiki, how do I generate a manual or online help? I don't want to maintain two separate files.

If you have any recommendations on wikis that have advanced WYSIWYG editors and allow you to customize the wiki code, let me know. Also, if you have actually worked on a project where a wiki was used, please tell me about it.

Several people today explained some of the drawbacks with wikis. Sure, the techies may inundate the wiki with irrelevant info; some of the info may be wrong and mislead users; some info may require more time reworking than if you had simply created it yourself. And so on. But c'mon, didn't Wikipedia prove that a properly guided wiki can be enormously more powerful than static content written by a limited staff?

Also, I'm not proposing that you remove the technical writer and just encourage the project members to create the wiki. I'm saying, let the technical writer use a wiki as his or her documentation base. Make sure all project members are familiar with the wiki's location and procedures for editing it. Then encourage the project team to comment, review, add, edit, and otherwise adjust the documentation through the life of the project. The writer can shape, stylize, make consistent, and organize the content to make it usable. Most likely the writer will write 75% of the content anyway, but it will be more informed and accurate.

(Thanks for the comments, Clyde.)