Lars Trieloff's Collaboration Weblog

My slides for my talk Supporting Technical Documentation Processes with Open Source Tools held at Linux Tag 2007 in Berlin are available at SlideShare: Supporting Technical Documentation Processes with Open Source Tools Slides.

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.

• Topic-oriented authoring
  Not DocBook vs. DITA, but topic-oriented authoring vs. narrative authoring. Norman Walsh says, tpoic-oriented authoring can lead to worse documentation quality due to measuring only coverage, not readability and usefulness.
  (tags: docbook techdoc)
• Inkscape 0.45 - A Pretty Blurry Release | FootNotes
  Inkscape is a remarkable open source vector graphics program, I use it for creating icons for the Mindquarry Collaboration Server.

  (tags: inkscape software macosx gnome cool)

Via Gordon Meyer I found Dan Wood's weblog. Dan is one of the developers of Sandvox - one of the easiest and best-looking ways to publish a web site (I've blogged about Sandvox before) and describes his technique of using a Wiki for creating a user manual.

The important thing to note here, is that the Wiki is not the user manual, it is just the tool for creating it. Most wikis have serious problems with usability when they are used as user manuals (no wonder, they are designed to ease the publishing and editing process) - an issue Dan mentions and one thing Dan does not mention, but that often occurs in Open Source projects: Wikis are a good excuse for forgetting documentation and delivering bad documentation.

What Dan and his team does is authoring the manual in the Wiki, then converting it into a proper Mac OS X online help. From my point of view, Wikis are not the optimal tool for authoring technical documentation, there are many specialized tools for this purpose that yield higher productivity, but this does not mean that Wikis do not have their place in a technical documentation process.

Wikis are ideal for drafting documents, creating content outlines and collecting resources before writing technical documentation. When it comes to actually writing documentation, specialied tools like XML-editors for DocBook come into play. In an ideal world you could at this point continue using the Wiki-principle of collaborative authoring and with Mindquarry's combined versioned file sharing, wiki and task management you've got all tools in one package.