Wiki eases the burden of creating documentation

Even in tightly run development shops, maintaining documentation can be a challenge, especially during the implementation phase. When documentation is required, it’s frequently an afterthought. When it comes to transcribing documentation, accuracy can be lost.

How can you provide timely, easily accessible documentation without the usual problems of the formal documentation process? Install a WikiWikiWeb, or Wiki for short.

WikiWikiWhat?
“Wiki Wiki” is Hawaiian for “quick,” and it’s an appropriate name. A Wiki is a collaboratively edited Web site designed to promote the accumulation and refining of data with the least possible hassle. Any user viewing a Wiki can edit anything they see quickly and easily. Using a Wiki is like browsing a collection of linked word processor pages. You don’t need to know HTML or any other markup language to contribute to a Wiki.

The first Wiki was at the Portland Pattern Repository. It’s still in active use and has over 20,000 Wiki pages, including a Wiki Wiki Web FAQ page. From that first example thousands of other Wikis have been created. Dozens of software packages provide Wiki functionality. Wikis can be publicly accessible or internal to a company.

Installing the Wiki
You must install a Wiki before you can start documenting in one. A quick Web search will uncover a wide variety of Wiki software, all with the same basic features. They differ in the languages in which they’re written, their Web server and operating system requirements, and the auxiliary features they provide.

I’ve tried many of the available Wiki software packages and I prefer a free one called MoinMoinWiki. MoinMoin has the right mix of ease of use, ease of installation, and power. It’s also available for Windows, Linux, and Mac OSX server platforms.

After downloading the MoinMoin software, follow the simple installation instructions. In no time you’ll have a Wiki of your own.

Using the Wiki
Once your Wiki is installed, navigate to it with your Web browser and take a look at the front page (see  Figure A). It has some general instructions on using Wiki that few will actually read. You can quickly dress up the drab home page to your liking.

Figure A

Wiki front page

Click on the Edit Text link at the bottom of the page. Your browser will display a large text area that contains the full text of the page you just viewed, as shown in  Figure B. At this point you have two options. You can insert text that your coworkers will actually read above what’s already there, or you can just replace what’s there entirely.

Figure B

Editing a Wiki page

What text you decide to add doesn’t matter a great deal at this time. All the Wiki pages will be revised again and again, but none so much as the front page. I usually start a new Wiki with some terse introductory text and links to a few pages that can be quickly populated by first-time Wiki users. I’ll explore some examples later in this article.

This, of course, begs the question, “Just how does one add links to a Wiki page?” The process couldn’t be easier. To create a link on a Wiki page, simply place two capitalized words next to each other with no space between them. For example, in this sentence the string WikiWord would be a link. It would link to a Wiki page named WikiWord. If, when browsing through the Wiki, a user clicks on the WikiWord link, they’ll either be taken to the WikiWord page, if it exists, or be asked if they want to create the new WikiWord page.

This simple link syntax, coupled with the ability to link to pages that don’t yet exist without getting an unsightly 404 error, allows for easy, organic Wiki growth. For example, you might be writing a page about Linux and include the word LinusTorvalds, intentionally omitting the space so as to create a link, without any intention of creating a LinusTorvalds page. If later someone is reading that Linux page and figures they know a little about Mr. Torvalds, they can click on the link, choose to create the page, and bash out a few sentence on the topic—which in turn can include links to other nonexistent Wiki pages to be created later.

Selling the Wiki
After creating your Wiki, you’ll find it takes very little effort to move documentation efforts into it. All you need to do is create a little content your future converts will find compelling. The best place to start is on the front page. I usually remove most of the built-in content on the front page and replace it with links like CompanyEmployees, DocumentationLinks, ExternalResources, and FunnyStuff. I then create these pages by clicking on the links and agreeing to create the new pages when asked to do so. On the CompanyEmployees page, I place a link for each of the developers on the project. Names make excellent Wiki links, and it’s a rare developer that won’t click on their own broken-link name to create their personal Wiki page.

The other pages can contain simple URLs that the Wiki software will also turn into clickable links when displayed. Gathering links to all the internal and external documents to which project developers frequently refer provides a convenient sort of shared bookmarks page. It’s often enough to pull others into the Wiki fold by itself.

Living the Wiki life
Once you have some content in the Wiki, you need to start promoting it as the place to find project resources and tidbits. Answer as many information requests as possible with “It’s in the Wiki,” even if you have to quickly enter the requested information before the requester gets a chance to look for it.

The Wiki makes a wonderful place to store little bits of knowledge too small to fit into documents of their own. Development account information, deadline listings, and miscellaneous tip and tricks make great Wiki fodder. Before long you’ll find that the Wiki is the first place project members look when trying to track down a nugget of information.