Section 12.2. Wiki Technology

12.2. Wiki Technology

To make a web site (repository) full of pages that are easy to update, use a Wiki. A Wiki is a concept, not a particular software package. There are many software packages that give you the Wiki feature. There is the original Wiki (Hawaiian for quick), then there is TWiki, KwikiKwiki, PHPWiki, etc. It's such a good idea that plenty of people have written software systems that give you the feature.

I ignored Wikis because I thought the name was stupid. I thought, "I could never use a system with a goofy name like that, even if it turned lead into gold." I didn't even investigate to find out what a Wiki was. Three years later, I started using a Wiki that someone else had installed and found it extremely helpful to my productivity. Oh, how I regret ignoring Wikis for so long.

So what the heck is a Wiki?

It is a web site in which anyone can edit any page, and linking pages is really easy.

Sounds crazy, right? I mean, if anyone can edit any page, what about vandalism? Someone could come along and delete things, put incorrect information into the system, and so on. It would be a disaster!

I promise you that there are some features that completely eliminate these problems. First, let's just consider the positive side:

• It's easy to add new pages. New pages can be added by anyone. If a junior admin is the first to deal with a new vendor, he can add a page for the vendor and start listing contact information and so on.

• Wikis are centralized and accessible. Anyone with a web browser can access them (allowing for any access controls in place). No special software is required on the client.

• Everyone can contribute. Anyone can edit any page when she sees a typo or has information to add. A document might start as a small checklist, then items are added by someone else, and someone else turns it into a full-blown process document.

• Wiki pages stay up-to-date. When anyone can edit any page, you've solved one of the biggest problems with documentation, which is that documents often become out-of-date the moment they are published. Instead, a Wiki is a set of pages that can be updated immediately by the person who spots the dated material.

The problem with document repositories is that there is usually a high barrier to use them. Users have to request an account, be given permission and access, etc.

12.2.1. Wiki Notation and Page Linking

A Wiki lowers the barrier for all of those issues. You don't have to be specially trained to know how to use onelessons in HTML are not required. You don't need an account to read documents. If you don't have an account when you go to edit a document, you are given the opportunity to create one right then and there. Accounts are created with default permissions that let users do most basic functions. And best of all, while users can write in pure HTML, there is also "Wiki notation ," which lets them write plain text that the Wiki formats. For example, Wikis understand that words surrounded by asterisks, underscores, and other symbols are special. If you type *like this*, it is displayed like this. If you type _ _like this_ _, it is displayed like this. If you make a bulleted list by starting a series of lines with *, Wiki transforms those lines into an HTML <ul> bulleted list. Most people pick up these codes very quickly because they use them in email already, and, if they don't, there is plentiful online help explaining the formatting.

Creating links in Wiki is easy, too. If you include a URL, Wiki turns it into a link. However, linking to other Wiki pages is much more fun. Wiki pages have names that are in a special format called a WikiWord. Perl programmers know this as CamelCase or StudlyCaps. It is simply a single word with mixed capitalization. For example, you might name a page ListOfFavoriteThings. Any time you write a sentence on a Wiki page that includes ListOfFavoriteThings, the Wiki turns that word into a link to that page, even if there is no page by that name. In that case, clicking on that link gives the user the opportunity to create a page with that name. In other words, to create a new page, just make a link to it, click on that link, and start editing.

It's also easy to upload documents into a Wiki. The document becomes attached to that page. Therefore, any page can become a document container for PDFs, Microsoft Word documents, and so on. Once, I needed a way for nontechnical people to store Microsoft Word documents. I simply made a Wiki page called TheProjectName and showed them how to upload documents so that the documents were attached to that page. The Wiki displays a table of what files are attached to the page automatically. If a person can't grasp Wiki notation, at the least he can attach documents to a page. A division of labor is created: experts create Wiki pages and structure the repository, less-technical people attach documents to the structure created for them. As those less-technical people get comfortable with Wiki concepts, they make an easy transition to the more technical tasks.

12.2.2. Preventing Wiki Vandalism

There are social controls and technical features in Wikis that combine to make sure vandals and malcontents don't destroy repositories.

First of all, the social controls are quite simple: every change is logged to the person who made the change. You'd be amazed at how effective this is. I estimate that 90 percent of the reason that people don't just go changing things willy-nilly is due to the fact that they're being logged. This is especially true in a corporate environment.

There are also technical features that control vandals. All Wiki pages are kept in a system like RCS, CVS, Subversion, or Microsoft SourceSafe. Thus, there is infinite un-do. You can roll back changes easily, or compare different revisions to a page to see exactly what was changed. Knowing that your vandalism can be undone easily often takes the joy out of the act. If spray paint washed off with the next rainstorm, there would be no joy in writing, "Francine loves Harvey" on a nearby overpass.

Most Wikis have access control systems. Each page or set of pages can be restricted as to who can read, write, or rename the page. The default is that anyone can edit the page, thus encouraging "the Wiki way." However, you want your main page, menus, and other pages to be editable only by designated people.

Wiki purists claim that access controls like this aren't needed because the beauty of Wiki culture is that while it is easy for one person to vandalize a page, it is just as easy for someone else to correct the page. That's true, but I sleep better at night knowing that I'm the only person who can edit the page that lists the phone number of my IT department's helpdesk. In Wiki culture, "a Wiki with business features" is code for "a Wiki with access control."

The coup de grace against Wiki vandalization is email notification. Most Wiki systems can send email notifications anytime a page is changed. The email usually includes what got changed (an HTML "diff" report) so that you can quickly see if the change was benign or harmful. Some systems default to always notifying the original creator of a page. Some sites configure a Wiki so that any change triggers a notification to the webmaster. I think that's overkill.

While documenting "everything" is a fine goal, never list a password on a web page. Even if the page is password protected and on a secure server, this is just asking for trouble. For example, I once found a site that was supposedly secure because passwords were listed on a page that was only accessible via an SSL connection after entering a password. However, people with shell accounts on the machine could log in and read the file directly. Since this was the main departmental server, everyone had accounts.

The Wiki system that I have the most experience with is called TWiki (http://www.twiki.org). Its claim to fame is adding access control. Other systems are available from the ultra simple (one is written in awk) to the extremely full-featured. Some larger systems are including a Wiki as a feature, while some systems are built entirely around the Wiki concept, such as the infinitely fun and amazingly complete open source encyclopedia project, Wikipedia (http://www.wikipedia.org).