HOWTO Install TWiki as a Corporate Intranet

By
-
163
– By Megan Golding, SecureWorks –

About six months ago, I installed a Wiki tool on my corporate intranet to help communications between and among departments. Specifically, I needed a way for the development group to collaborate on project documentation including requirements, test plans, and release plans. In the bad old days, corporate documentation was kept on a shared network resource in many formats and often in duplication. These days, the Wiki serves all internal documentation. Read on for my tips on creating WikiCulture at your company.Available Tools

Wiki is a concept, and you’ll find many tools that implement the concept. The original Wiki was written by Ward Cunningham and is located at http://c2.com/cgi/wiki. Cunningham’s Wiki is the Wiki, all the rest are known as Wiki Engines. Let’s look, briefly, at some of the options.

TWiki, Meatball, and MoinMoinWiki are three that have gained larger followings. Each of the Wiki Engines offers features not found in the original Wiki at c2.com. I settled on TWiki after an evaluation of several Wiki Engines. We were looking for revision history, professional look out-of-the-box, and change notification by e-mail. For an intranet with non-technical users, the look was pretty important to me. Wiki and Meatball have a spartan appearance that I doubt would be popular with non-technical users.

TWiki is under the GPL and you can download it from http://twiki.org/download.html.

Installation Process

Want to install TWiki? Fortunately for you, TWiki is implemented in Perl using CGI, so if your web server can serve Perl CGI pages, you can install TWiki.

The best way to install TWiki is to read the installation manual. It provides ample detail in the installation directions. To give you an idea of the process, here’s an overview. For these instructions, I assume you’re running Apache on a Unix system:

  1. Un-tar the TWiki distribution into DocumentRoot of your web server. TWiki is made up of several CGI scripts in their own bin directory, a directory structure, and some basic content. After un-tarring, you’ll have data, lib, bin, and a few other directories.
  2. Tell Apache where to find the TWiki CGI scripts. TWiki will unpack the scripts under bin, by default. Your httpd.conf should have the following to recognize where the TWiki scripts are: 
    ScriptAlias /twiki/bin/ "/path/to/twiki/bin/"

    <Directory "/path/to/twiki/bin">
	       Options +ExecCGI
	       SetHandler cgi-script
	       AllowOverride all
	       Allow from all
    </Directory>
  3. If Perl doesn’t live in /usr/bin on your system, modify the CGI scripts in bin to use the correct path, or create a /usr/bin/perl symlink to where Perl lives in your system.
  4. Modify file permissions so the Apache user can execute the TWiki scripts and write to the TWiki data files.
  5. Edit the TWiki configuration file to fit your environment. 6. Enable basic authentication so changes are associated with registered users. See http://twiki.org/cgi-bin/view/TWiki/TWikiUserAuthentication for more detail.
  6. Remove unnecessary TWiki user accounts (but not TWikiGuest) from data/.htpasswd
  7. Load the testenv script to check the installation. This excellent feature tests the variables, permissions and configuration settings that TWiki uses to live and tells you if there are problems. Any errors will be displayed and the script suggests how to fix them. In fact, you could probably skip step 4, above, and work off of the output from testenv.

For an intranet installation, it makes good sense to enable TWiki authentication. When a user edits a page, he or she will be prompted for a username and password. There are two immediate benefits to using authentication: changes are associated with user names and portions of TWiki can be restricted based on user name. Rather than reinvent the authentication wheel, TWiki is designed to work with the web server’s authentication framework. The TWiki installation instructions provide excellent detail on configuring TWiki to use Basic Authentication.

Getting Buy-in

Let’s face it, Wiki is an odd concept with which most intranet users aren’t familiar. While establishing Wiki at my company, I fielded questions such as, “Who updates these pages?”, “How do we lock it down so the wrong people don’t edit certain topics?”, and even “What if someone changes a page I create?” Getting buy-in from a broad base of users in a company is vital to Wiki success.

Start by identifying what content you want to see in the Wiki. Development process documentation is a natural and well-established use of Wikis. Consider using your Wiki as an employee directory, new employee handbook, and resource for questions about how things are done. Write this list down. Better yet, add this list to the Wiki.

Before you show anyone your new Wiki, add some sample content. Better yet, if you have it, add real content. Take development announcements from e-mail messages, requirements documents from a shared network resource. Aim to have ten to fifteen topics in the Wiki before anyone sees it. If you show off an empty Wiki, few people will have the vision to see how it’ll be useful to them. Even hard-core techies and tool geeks will appreciate seeing Wiki in the context of your organization.

Next, identify key people in the organization who can help get buy-in. These aren’t necessarily managers and senior folks. In fact, you should target folks lower down the food chain. These people will become your Wiki evangelists. Choose them well. Look for people who are good communicators — they’ll make excellent content contributors in the early days. Also, look for the information consumers within your organization. These are the people who read everything that gets sent out to them. Early on, consumers will be important for spreading the word about finding information on the Wiki.

Now, visit your Wiki evangelists individually. Its important to establish individual Wiki-relationships with your evangelists. Don’t hold a training session with everyone in attendance. You’ll sabotage the process. Fifteen minutes alone with each evangelist — at their own workstations — will be ample time to familiarize them with the tool. Tip: Ask each evangelist to bookmark the Wiki in their web browsers before you leave their office.

Random Tips

I’d like to close this article with some tips I’ve gathered from my work with TWiki. They’re by no means exhaustive of Wiki-fu, but they should give you some ideas.

Rule of Two: Writing an e-mail message to more than two recipients? Add the message to the Wiki and send a link to the content. That way, everyone can see the message. Very helpful in keeping people in the loop.

Slow Adoption: Allow time for Wiki adoption. Three months or longer is not unusual for wide-scale adoption in a small company. You’re waiting on two things: people’s habits to change and the trickle-around effect from your evangelists.

Techies Rule the Wiki: Chances are, Wiki content will be dominated by the techies in your organizations. That’s ok. Let the techies contribute scads of information because it’ll offer a valuable insight into an often under-heard portion of the company.

Individual Training: As I mentioned earlier in getting buy-in, work individually with your Wiki evangelists. They’ll be key to spreading the word about it. Spend fifteen minutes with evangelists and other new Wiki users. Explain WikiCulture, basic formatting, and where to go for more help.

Intranet Deployment Tips

These links on twiki.org are invaluable for deploying TWiki on an intranet.


TWiki has improved internal documentation so much at SecureWorks, where Megan implemented it over 9 months ago, that the developers write more than she does! Founded in 1999, Atlanta-based SecureWorks is an Internet security company that protects corporate networks against hacker attacks. Hundreds of banks, credit unions, utilities, and professional services firms across North America rely on SecureWorks for Rock-Solid, Four-DimensionalSM network security with no hassles, no headcount, and no capital outlay. For more information, visit SecureWorks on the web at http://www.secureworks.com or call (877) 905-6661.

RELATED ARTICLESMORE FROM AUTHOR