Use a wiki to integrate your information systems

Managing documentation and support requests and collaborating effectively are difficult tasks for many organizations. Most companies have separate systems to track customer information, handle support, and manage a general knowledge base, but when someone needs a 360-degree view of a project, or needs to find all of the information on a client, the task can be next to impossible. Why not glue all of your 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 types of collaboration applications, but what distinguishes a wiki is its ability to allow an infinite number of users to add, edit, share, and link content easily, without any knowledge of the underlying system.

Suppose you are the manager of a software product team at a midsized company. Your product is installed at 25 client sites, and you have a team of five developers and two software testers. All of your code is kept in a CVS repository. You track software bugs and requests in Bugzilla. Help desk support tickets are in RT, and client site information is housed in SugarCRM. All of these applications are running on the corporate network. Your boss, the CTO of the company, wants to see the specs for version 2.0 of your product, 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. He wants a report by Friday, and a new report every week until the release date.

Many managers would gather all of this information from different systems and people, create a report, and repeat the process every week — but all that work is unnecessary. An easier way to handle the task is to install a wiki into which your team can enter and update all of the requested information. The team shares the responsibility of keeping the project information up to date, you stay organized, and the boss gets more than he asked for.

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 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, as most now do.

Popular wiki software

There are hundreds of feature-rich wiki packages available, many of which, including all the following, are free. The WikiMatrix Web site provides a wealth of information about wiki software. Three popular choices to consider:

WikiMedia powers the Wikipedia site. 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 uses a MySQL back end. It’s offered primarily as a hosted solution, and has an integrated WYSIWYG editor.

MoinMoin is written in Python, is simple to set up, and does not require a database.

Extending a wiki

Most of the time users enter text information directly into a wiki, but wikis can also pull information from other applications if you know how to add some custom code. For instance, suppose 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. You may be able to just type <issue>12345</issue> into a wiki page and have the wiki software go to the issue tracking database and display the information about the issue.

Most wiki packages consist of two components — a parser and a renderer. Generally, all you need to do to extend the components is add a few simple lines of code. To satisfy the issue tracker scenario above in MediaWiki, for example, you can use a PHP script like the following:

<?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;
}
?>

Consult the documentation for the wiki you use for the exact details on extending the parser and the renderer.

Building a wiki from scratch

If you need more of a custom implementation than a wiki package can provide, there is no sense in starting from scratch. You can choose from several wiki parser/renderer libraries 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. Two wiki libraries worth looking at are:

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, and 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 is not a silver bullet solution to collaboration and information-gathering issues, but it can help.

Chad Files, a software developer from Arkansas, has been developing Web-based applications for more than 10 years, and is a contributing developer to many open source projects.