Author Note: This was originally posted on linux.com in 2008. I am replicating it here for posterity.

Managing documentation, support requests and collaborating effectively are difficult tasks for many companies. Most companies have separate systems to track customer information, handle support and manage a general knowledge base. There is nothing wrong with that; however, what happens when you need a 360 degree view of a project, or need to find all of the information you have for a client — for most businesses, the task becomes next to impossible. Finding a single solution to mange all of these tasks is probably not going to happen either, so what is one to do? Why not glue all of the separate systems together using wiki software.

The primary purpose of a wiki is to allow users to collaborate in an open space. There are many other types of collaboration software packages available, but what separates a wiki is the ability to allow an infinite number of users to add, edit, share, and link content easily, without any knowledge of the underlying system. These attributes allow wikis to be ideal tools for collaborating and sharing information.

How to Apply a Wiki

Lets assume you are the manager of a software product team at a mid-sized company. Your product is installed at 25 client sites, and you have a team that consists of five developers and two software testers. All of your code is kept in a CVS repository, software bugs and requests are in bugzilla, help desk support tickets are in RT, and the client site information is housed in SugarCRM; all of these software packages are running on the corporate network. Recently your boss, the CTO of the company, has been very interested in the progress of version 2.0 of your product. He wants to see the specs, know what features are being added, make sure that issues from version 1.0 have been resolved, see the test plan, and see which clients need to be upgraded. One more thing, he wants it by Friday and wants a new report every week until the release date.

A great deal of managers would go and gather all of this information from the different systems and people, create a report, and repeat the process every week. All that work is not necessary, an easy way to handle this is to install a wiki. By creating a wiki your team can put all of the requested information in the wiki, and update the content as needed. The team shares the responsibility of keeping the project information up to date, you stay organized, the boss gets more than he asked for, and the company can now apply the same principals elsewhere now that  a wiki is available.

There are a few common pitfalls to be aware of when using a wiki. Many non-technical people may have issues understanding exactly what a wiki is and how to use one. Often times this issue can be remedied by performing a small informal training session. Some people may get the concept of a wiki but not be apt to learn wiki syntax. If this is an issue consider using wiki software that has a WYSIWYG editor; most of the popular wiki applications have these now.

Popular Wiki Software Suites

There are hundreds of feature rich wiki software packages available, many of which are free. The ones mentioned here are a few of the more popular, and all are available for free.

WikiMedia – powers the popular Wikipedia. It is written in PHP and runs in a typical LAMP (Linux Apache MySQL PHP) stack; it can handle a large number of simultaneous users.

SocialText – is written in PERL and is backended by MySQL. SocialText is offered primarily as a hosted solution; it has a nice integrated WYSIWYG editor.

MoinMoin – written in Python, it is simple to setup and does not require a database.

The WikiMatrix website provides a wealth of knowledge on most wiki software packages.

Extending a Wiki

Using a wiki as a knowledge base is beneficial but has its limitations. Often there comes a point when you want to do more; for instance, say you want to publish software release notes on a wiki, but you do not want to spend the time creating links to your issue tracking system. What if you could just type <issue>12345</issue> into a wiki page and have the wiki software go to the issue tacking database and display the information about the issue? With most of the wiki packages available you can do just that.

Most wiki packages consist of two components, a parser and a renderer; generally, all that is need to extend the components are a few simple pieces of code. For example, to satisfy the issue tracker scenario above in MediaWiki a PHP script like the following is all that is required.

<?php
// meta information about the extension
$wgExtensionFunctions[] = 'wfIssue';
$wgExtensionCredits['parserhook'][] = array(
    'name' => 'Issue Tracker',
    'description' => 'Display Issue Information',
    'author' => 'Joe Coder',
    'url' => 'http://example.com'
);

// hook into the parser
function wfIssue() {
    global $wgParser;
    $wgParser->setHook('issue', 'renderIssue');
}

// the call back function that formats the issue information
function renderIssue($input) {
    // connect to the database and get the issue
    $dbo = new DB("mysql://localhost/database/user:password");
    $rs = $dbo->query("SELECT * FROM issues WHERE id = {$input}");
    $row = $rs->getRow();
    
    // format the outpur
    $output = "{$row["title"]}<br/>{$row["description"]}<br/>";
    return $output;
}
?>

Why stop there though, wiki software can be extended to support CRM (Customer Relationship Management), ERP (Enterprise Resource Planning), and billing systems. There is no need to replace software that is working well. This approach opens the possibility of pulling all of them together.

Building a Wiki From Scratch

Sometimes prepackaged solutions do not work and a custom implementations are needed; wiki software is no exception. However, there is no sense in starting from scratch; there are several wiki parser/renderer libraries available to use as a base. The libraries do the heavy lifting of reading and formatting the wiki text. In most cases all a developer needs to do is add a storage facility implementation that wraps the library. Here are just a few of the wiki libraries available.

Text_Wiki – written in PHP, it accepts its own style of wiki text and outputs XHTML. The library provides an easy to use API to extend the wiki text language. The structure of the library also allows developers to create their own parser and renderer rule sets.

CGI::Wiki – provides the same features and functionality as Text_Wiki, and a little more; it is written in PERL.

Conclusion

Using a wiki in a daily workflow is not a silver bullet solution to collaboration and information gathering issues; often they will help though. Many companies, even those without IT, have already discovered the benefits of using wiki software, and as time goes many more will too.