Introducing UseModWiki

Wiki software implements the simple idea that Web pages should be easy, even trivial, to create, and that anyone reading the page should be able to correct, improve, revise and add to the page. Wikis (the word means “quick” in Hawaiian) have become popular on the World Wide Web. With simple formatting rules to make it easy to build well-organized hyperlinked pages, a wiki becomes an efficient means of creating a Web site. One worthwhile wiki for business collaboration is Clifford Adam’s UseModWiki.

UseModWiki is a single Perl script that can be deployed on any Web server that supports CGI scripting. It keeps its data in simple flat files (no database back end required) using modules that are part of the standard Perl installation. As a result, the overhead in terms of preparing a machine to run your wiki is quite low.

You can downloadUseModWiki from the project’s Web site in the form of a small (63KB) tar file that contains the primary Perl script (wiki.pl) and a few other related files. The installation instructions are straightforward and consist mainly of placing the wiki.pl script in suitable location on your Web server and editing it and an optional configuration file to set your site-specific behavior.

Once you’ve installed the software, you can give it a spin by typing in the appropriate URL. You should see a minimalistic home page. You need to take some time to think about how you want to integrate the wiki into your team’s operations and modify the software’s settings accordingly.

You’ll want to make the initial wiki page as useful as possible. Add links to any important internal Web-based resources that your business may have: the company Web page, the human resources department’s policy pages, and so on. If you use syntax like [http://www.newsforge.com NewsForge] when you edit the page to add a link, it will appear as [NewsForge] when others view the Web page. You’ll also want to provide some wiki introductory material accessible from the home page so that newcomers to your wiki aren’t totally lost.

In addition to the links you’ve already added to the main page, add two wiki words — FormattingRules and SandBox. With this capitalization, the wiki software interprets the words as indicators of special kinds of pages, and creates two new pages with those names. When you save the home page you’ll see those two words with question marks next to them. The question marks indicate that the pages haven’t had any initial content created.

First click on the question mark for the SandBox page to invoke an editor for that page. This page lets people experiment with wiki formatting rules and get comfortable with the unusual role of being one of the authors of all of the pages of the wiki. Put some informative and encouraging text in the page to start with.

Now edit your FormattingRules page (again by clicking the question mark next to the word on the home page). Open another tab or browser window and also edit the TextFormattingRules page of the UseModWiki Web site. Select all of the text on that page and paste it into your own formatting rules page. You’ll want to review what you’ve pasted into your site to make sure that the information presented is appropriate and useful in your environment. Remember that your site’s users will able to adjust this (and all other pages) to suit their needs.

Once you’ve got the basics taken care of it’s time to think a little bit about how your user community will actually use the wiki. For development teams, for example, a wiki is an outstanding place to hold small design descriptions or documentation. To facilitate this, you can take advantage of the interweb feature of UseModWiki, which allows you to create tags that allow your users to quickly create links to other Web resources.

To begin using interweb tags, copy the “interweb” file that came in the UseModWiki tar archive into your wiki database directory. Now, as an example of how to use it, consider a Web access service for your source code control system (like WebSVN or WebCVS) that allows you to reference source files with a URL of the form http://scm.myco.com/scm.cgi?FiLE=/trunk/main.cc. If you add an interweb entry of the form code: http://scm.myco.com/scm.cgi?FILE= your users will be able to reference source files by simply entering code:/trunk/main.cc. This makes it easy to document a project. You can do something similar with your bug database or job tracking system.

Finally, the UseModWiki community has provided a number of patches to the UseModWiki code to add features or customize the behavior of UseModWiki. Typically they are presented as a series of instructions for adding, modifying, and deleting code in the wiki.pl file. If you’re not comfortable doing this, buy your local Perl wrangler lunch and ask him to apply the ones you’re interested in.

One patch that I’ve provided allows users to add their email addresses to the “/Mail” sub-page of any wiki page in order to be notified that the page has changed. In the communities that I’ve worked with, this has allowed the creation of ad-hoc discussion groups subscribed to a particular page. In effect, that page gets edited collaboratively by the folks on the “/Mailing” list until they reach consensus on the issue at hand. If you use this patch you should also consider the PerlDiff patch, which presents the revisions to a page in a somewhat clearer fashion than the default presentation.

Once you’re happy with the way you’ve configured your wiki it’s time to roll it out to your team. Gather them together where they can see you manipulating the pages in a Web browser. Start by giving them a quick introduction to the idea of wiki software and then get right into the SandBox page. Make a few sample pages, show off the formatting rules, and demonstrate UseModWiki’s ability to show the revision history of any given page (at the bottom of the page is a “Show Revisions” link). This last is crucial because it reduces some of the fear of editing a page. Take suggestions for pages and page hierarchies that might be useful to the team and stub them in while everyone is watching. Encourage people to create their own personal pages if they’re so inclined. Make it clear that if, as a reader, they encounter something on the wiki that is wrong or unclear or limited, they can instantly become authors and editors of the information themselves. At your next design meeting, use the wiki to take notes (this can be especially effective if you can do so using a meeting room projector or large monitor that allows the participants to see your edits). After only a little time, this sort of usage will become second nature.

You can deploy UseModWiki with just a few hours of work (and an hour for lunch with the Perl wrangler, if you need to). I’ve been involved with communities of not much more than 10 people that produced hundreds of wiki pages in just a few months. Obviously not all of those pages are useful all of the time, but at any given time, a good many of them are crucial. In the long run, the phrase “it’s on the wiki” will become common with your team.

Keith Fieldhouse is a software developer living in upstate New York.