Search results

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.)

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.