Lars Trieloff's Collaboration Weblog

Wikis are a hot topic in technical documentation. Adrian Sutton has some interesting remarks why he thinks, Wikis and user-contributed documentation do not lead to high-quality documentation: Creating Great Documentation:

First and foremost, if you're thinking about improving a product's documentation, read Kathy Sierra's How to get users to RTFM. Make sure your documentation covers each of the five types required: Reference Guide, Tutorial, Learning/Understanding, Cookbook/Recipe, Start Here.

Adrian says that Wikis tend to create mostly reference documentation. Additionally Wikis are not versioned with your products source code.

I would add that Wikis often lead to topic-oriented authoring, Norman Walsh has some interesting takes on the consequences of topic-oriented authoring: Good for reference, bad for tutorial, learning and understanding, bad for start here documentation.

Scott Abel points me to Tom Johnson's Using Wikis as Project Documentation Tools. His main complaints are:

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.

I would agree to this complaints because Wikis are not the best tools for technical writing, they are websites that are easily editable, nothing more and nothing less. But there are reasonable arguments for using Wikis and user-contributed feedback for documentation:

I’m saying, let the technical writer use a wiki as his or her documentation base,” says Johnson. “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.

Wikis and user-contributed generation are a way of generating feedback and an additional source of information of the technical writer. Another example are the user-contributed comments of the PHP documentation Adrian points to.

My methodology of creating technical documentation uses Wikis in two places:

1. I plan and organize the documentation project using an issue tracking system and create tasks for every step in the documentation process
2. I 'harvest' product development Wikis for information about the software I am documenting. This is the first use of Wikis - a source of information
3. I create a content outline of the planned document in the Wiki and invite other team members to comment and correct the content outline. The Wiki here is a space for distributed brain-storming.
4. I write the document using DocBook-XML, WYSIWYG-XML-editors and share the in-progress document and illustrations using a version control system. As I am using DocBook and Mindquarry's file sharing, concurrent editing of modular documents is easy.
5. Reviewers and copy-editor use the issue tracking system to create comments and remarks to the documentation.
6. After releasing the document, the issue tracking system is used to track comments and suggestions for improvements. As the Wiki keeps evolving I have a good starting point for a second revison of the document.