Paper. I just hate it. For years, the IT industry has tried to make employees more productive by providing means for them to collaborate electronically (read: lose the paper). We now have LDAP servers, Domino Server, Microsoft Exchange, and a host of other groupware--all of which were supposed to be the be-all and end-all of collaboration. But even with all of this great software and despite your best efforts, I'll wager that if you take a stroll around your company, you will still find Post-it notes and typed lists stuck to the computer screens and office walls. Why is that? Why do people continue to maintain these islands of non-sharable information?

Based on my observations, I'd posit that it's because none of the fancy tools that we offer have the flexibility or simplicity that the users want or need, so the paper notes persist. Dissatisfied with this state of affairs, I decided to take on the challenge of finding a tool that would spell the death of Post-it notes in my company. How well I did remains to be seen (it's too soon to tell), but the project has been interesting. This month, I'll share with you the product categories that I investigated and the solution on which I settled.

Easier Than Paper

From the onset of the project, I was determined to use a browser-based solution. I did this primarily for two reasons. First, everyone knows how to use a browser, and virtually everyone is comfortable using one. I wanted to offer the users a familiar tool, thus giving them less of a reason to fall back to paper. Second, I wasn't interested in any solution that required the installation of additional software on the clients. If a user just once lacks access to his notes because the requisite tool is missing (if he were working at a different workstation, for instance), then it's guaranteed that he will revert to written note-keeping. So choosing to use a browser all but eliminates the problem, since browsers are ubiquitous and require no additional management from the IT department (a definite plus).

Choosing the human interface for this package (a browser) was the easy part. More difficult was the choice on how to store and retrieve the users' notations.

The obvious choice is a combination of HTML documents and a Web server, since the creation of such documents is trivial using OpenOffice, Microsoft Word, Netscape, or Mozilla. Equally trivial is configuring a Web server to dish out documents from somewhere in the user's home directory. Unlike the advanced software I earlier mentioned, HTML documents offer the ability for the user to have a completely free-form venue into which they can place their information. Sure, it's not structured. But neither is the information on those cursed notes! We have all seen examples of this technique; the URLs look like this: http://some.domain.com/~joeuser. I have to admit that I gave this combination a try, with extremely limited success. While HTML can itself be complicated for the average user, the biggest stumbling block I ran into is the concept of hyperlinks. To an IT guy, hyperlinks are nothing special. But if you find life boring and want a challenge, try explaining hyperlinks (or HTML itself) to a bunch of nontechnical users. It's a challenge guaranteed to have all but the most patient banging her head against the wall. There are nice site generation tools that make hyperlinking a nonissue, but then you're back to installing custom software on the clients--something we determined to be unacceptable. And of course, there is the prevailing question: Is using an HTML editor really easier than using paper? Most users will answer with an emphatic "No!"

I next considered using a content management system (CMS) for this task, such as Postnuke (described in "The Linux Letter: Nuke It"). I quickly discounted this idea though. While a CMS has nice features (not the least of which is the search function), it also suffers from complexity. Users have to log into the CMS (yet another hassle), and there can be a significant learning curve for users to overcome before they'll become productive. CMSs work great for extranet/intranet sites but are orders of magnitude more effort to use than paper and a lot less flexible. Thus, I assumed that my users wouldn't bother using one, so I didn't go down this path.

Searching further for a good solution, I decided upon a cousin to CMS, a piece of collaborative software known as a wiki.

What's a Wiki?

Whenever I suggest wiki software to someone unfamiliar with the term, I unfailingly get a "deer in headlights" look and the question "What's a wiki?" A wiki is a CMS with a special attribute: Anyone can edit the contents of the site. It creates the ultimate collaborative Web site. The name "wiki" comes from the Hawaiian term wiki wiki, which translates to "informal" or "quick." Once you see a wiki in action, you'll understand why it is so named. Making a change to a page can be simplicity itself.

Many open-source projects use wiki software to manage their documentation, allowing users to make corrections and clarifications to the docs. I could point you to one of these open-source projects, but instead, I'll point you to the ultimate example of a wiki: Wikipedia, the free online encyclopedia. When I last visited the site, it boasted of having 610,511 articles written in English. For some fun, you should surf to the site and do a quick search (search for "wiki" perhaps?). Click on one of the results, and you'll find something that may surprise you. Every article has an Edit button that allows you to edit the text of the article you are reading. That's right: You can make changes to text, and those changes will become immediately visible to subsequent visitors.

I can already hear the gasps from the security-conscious: "Do you mean that anyone can make changes to the content without any kind of authentication?" Yep, that's exactly what I mean. The whole paradigm around which wikis are designed allows and encourages this. It's what makes collaboration so easy using this software. Sure, a public-facing wiki is subject to the occasional vandal or spammer. But most wiki software has a roll-back feature that makes clean-up simple. And frankly, the benefits of a wiki far outweigh this minor inconvenience.

I could go on about the virtues of wikis, but Wikipedia already has a good, succinct description of the wiki concept, so I suggest that you surf on that link and read it there.

Which Wiki?

While all wikis are designed around a standard set of functions, there are many variations in implementation and focus. The Wikipedia site has a Web page that lists a large number of wikis and includes a basic synopsis of each. You can browse that list to get an idea of the possibilities and requirements of each.

I was looking for a few specific things when I made my choice:

I wanted a wiki that used plain-text files for its data store. Some of them use a DBMS as the back-end, which is fine. But I wanted a wiki that could be viewed even if I booted its host machine in recovery mode, where all I had was a command line. Plain-text data stores have an advantage when it comes to generating pages with a script. I can pipe the script's output directly to a file in the appropriate directory and quickly include it in the wiki content.

Along those same lines, I wanted a wiki that didn't require any additional software other than my normal software load. That means that the most likely candidate would be either Perl- or PHP-based. While very few of my machines are without Java and Tomcat, I didn't want to have to ensure the presence of those two packages on every server that might host a wiki. On the other hand, I routinely install Apache (and PHP and Perl) on everything but the most disk-constrained systems, primarily because they're handy to have on a machine.

For the users' sakes, I didn't want them to have to use HTML to effectively use the site. Plain-text and simple mark-up would be a top priority. As I've mentioned, I want this to be as easy as taking notes on paper. Avoiding HTML also makes it easier to read the content from a command line, so there's a selfish motive at work too.

The choice I made was a wiki called Dokuwiki. It has all of the features that I require, is designed to make documentation simple, and is written in PHP. Installation couldn't be easier, assuming that you already have a working Web server.

Let's look at how easy this is. (If you don't want to load this software, but you'd be interested in seeing how it works, then I suggest that you visit the project site. There is a working "playground" where you can give Dokuwiki a try.)

Installing Dokuwiki

Obviously, you'll need to get the software before you can load it. Browse on over to the Dokuwiki download page and pick the latest version, which at the time of this writing is dated July 1, 2005 (Note: Clicking on the July 1 hyperlink will start the download). Save the downloaded file in the /tmp directory.

The following instructions are for a Red Hat-based system with the Web server in its stock configuration. This makes the DocumentRoot directory /var/www/html and the user under which the Apache Web server runs apache. If your site is configured differently, then make the appropriate changes to the commands that follow.

Open a command line and change to your Web server's document root directory:
cd /var/www/html

Extract the contents of the file:
tar -xzf /tmp/dokuwiki-2005-07-01.tgz

Change the resulting directory name into something more interesting:
mv dokuwiki-2005-07-01 mywiki

There is one file that you must create before you access the wiki for the first time; otherwise, you will receive an error. Just issue this command to create a blank file with the appropriate name:
touch mywiki/data/changes.log

Finally, you will need to change ownership of the entire directory and its contents to the apache user. This is done so that the Web server can write to files in the directory. (Actually, you can use a bit more granularity in granting permissions, but changing ownership of the entire directory is quicker.)
chown -R apache.apache mywiki

That's all there is to it. Point your browser at http://server/mywiki, and you should be greeted by the screen shown in Figure 1.

Figure 1: The presence of this screen denotes a successful Dokuwiki installation. (Click image to enlarge.)

If so, congratulations! You now have a fully functional wiki ready to serve your documentation needs. If you receive a 404 error (Page not found), then ensure that you have placed the wiki into the DocumentRoot directory and that you have no typographical errors in the name you gave the directory or the URL you typed into your browser. Should you receive a message that states "changelog does not exist or isn't writable. Check config!," then you forgot to either create the file or change the file's ownership to apache.

How Successful Have I Been?

Has this project been worthwhile? You bet! The wiki provides everything you could want for documenting your projects or keeping track of the information that's currently stuck to the walls of your office. Dokuwiki is searchable, allows the upload of graphics and other files, creates backward and forward links automatically, has full revision control and version "diffing." In short, I can't think of a product that does so much with so little effort.

My staff makes extensive use of Dokuwiki to document all of our systems. I have written a script that polls each of our servers, automatically creating individual text files that contain all of the information I need to know to manually recover a system. Another script builds an index page for all of these individual documents.

I'm currently training users in other departments on the wonders of the package. (Read: I'm currently giving sales pitches to other departments.) The software itself is almost self-evident. My training classes should be titled "Here's What You'd Use a Wiki For."

How successful have I been in getting other departments to use the wiki in lieu of paper? It's too early to tell because I haven't yet made the pitch to everyone. But I had an inkling of how well-received the wiki has been when a manager who always struck me as the "I'll use a computer when they pry my pencil from my cold, dead fingers" type expressed enthusiasm over his department's wiki. Hearing enthusiasm from him told me that I was on to something really good. I know that if you load up a wiki and give it a try, you will be onto something really good, too.

Barry L. Kline is a consultant and has been developing software on various DEC and IBM midrange platforms for over 21 years. Barry discovered Linux back in the days when it was necessary to download diskette images and source code from the Internet. Since then, he has installed Linux on hundreds of machines, where it functions as servers and workstations in iSeries and Windows networks. He co-authored the book Understanding Linux Web Hosting with Don Denoncourt. Barry can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it..

Barry L. Kline is a consultant and has been developing software on various DEC and IBM midrange platforms since the early 1980s. Barry discovered Linux back in the days when it was necessary to download diskette images and source code from the Internet. Since then, he has installed Linux on hundreds of machines, where it functions as servers and workstations in iSeries and Windows networks. He co-authored the book Understanding Web Hosting on Linux with Don Denoncourt. Barry can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.

Also Read

Practical OSS: MkDocs for the IBM i, Part 2

Practical OSS: MkDocs for the IBM i, Part 1

Practical OSS: MMAIL from EASY400