Wiki Patterns

What is it?

Many organisations are starting to use wikis for formal documentation, such as functional and technical specifications.

They may encounter resistance, because of some legitimate worries. In brief: Certain types of documents have a built-in obsolescence.

In more detail:

• Documentation gets out of date - even if you only have a small amount of it.
• Technical specifications are valuable at the time of product development. But in many cases the specs are not kept up to date with subsequent product enhancements.
• Agile companies don't want to become documentation-bound. Too much of a good thing can slow anyone down, especially if you have to keep it up to date.
• You cannot rely on someone to mark the documents as 'out of date' after the fact.

Usage

At the creation of such a document, the creator should declare its validity period.

Example

Some wikis, such as Confluence allow you to create a 'template'. When creating a page, you can base the page upon a specific template.

This wiki pattern suggests that you create a built-in obsolescence template. The template would contain something like this at the top of the page:

• The usual stuff, like product name and feature.
• Product release number.
• Document validity period e.g. June to July 2007
• A warning message along these lines:

  Beware of built-in obsolescence This document was written as an aid to initial feature development. It will not be kept up to date with later enhancements. After the validity period shown above, you can use the document for a broad overview of the functionality. But do not rely on the details.

Related Patterns

• Wikiphobia - by adding the 'built-in obsolescence' warning, we will allay the legitimate fears that incorrect information could spread throughout and even outside the organisation.
• WikiGnome, also known as WikiGardener - the 'built-in obsolescence' pattern will greatly ease the WikiGnome's job, because there's no need to trawl through the wiki marking pages as out of date.
• ContentAlert - another type of content alert.
• Set Window of Discussion - a way of forcing time sensitivity for (non-obsolescent) evolving documents