Channels ▼
RSS

Web Development

The Wiki Way


The Wiki Way

How does your team handle project collaboration? "In the beginning ... was the memo. And the memo begat the photocopy, and the photocopy the fax, and the three-ring binder. And, lo, the shelves did groan, and the stakeholders did paw through them in vain for the requirements, for they were misfiled and out of date besides, and the code reflected them not. And the programmers and stakeholders waxed wroth with one another, saying, 'Didst thou not get the memo, pinhead?'"

Of course, when documents became electronic, things got a little easier. And the advent of e-mail trivialized communication to the point that a project could be represented by little more than its message traffic. If anything, it was a little too easy, as nuggets of critical related information could spatter across message threads instead of accumulating in purpose-built, organized collections. But the problem remains: How do you manage a document's information artifacts so that they're accessible to all members, easily edited by the appropriate people, and their changes are propagated to everyone who's interested? Some serious skull sweat has been expended in this space. Here, I'll explore a rather humble category of collaborative tools—the wiki. A variety of other products can fit the bill, but if any vendor tells you that they've got The Answer, hang onto your wallet until you decide they're right. Some teams flounder in chaos; others grumble as they waste time on mega-process compliance tasks or try to short-circuit their way back to productivity.

You should know my biases: I heartily favor the Agile Alliance's "barely enough process" motto, yet I'm terminally addicted to cool new technology. I'm resistant to adding process, but driven to the point of considering tools, I get all starry-eyed. I'm also a 20-year Unix veteran, hence I'm likely to favor combining simple tools instead of seeking the One Solution. I also prefer to give lots of things a try instead of planning the be-all, end-all strategic home run.

Paradoxically, because they're so simple, wikis tend to be a little hard to grasp. Peruse one, and you're likely to wander around clicking links, achieving an overview only by dint of persistent peregrination. Wikis were invented by Ward Cunningham, of Extreme Programming fame, and in their original form are brilliantly simple: A wad of Perl scripts running a website, every page of which contains an Edit This Page button accessible by anyone. That's right—any Tom, Rick or Harriet can wonk on your carefully crafted prose, using nothing more than the browser they rode in on. To say this raises issues of security is like saying the Atlantic Ocean raises issues of dampness. Nevertheless, even if you eschew the ¼ber-democratic wiki philosophy (Google "WhyWikiWorks" for details), damage tends to be limited, since most engines support rollback of munged pages. The authoring language is usually somewhat-adorned plain text, which is converted on-the-fly to HTML for viewing. In the original wiki implementation, you create new pages by editing existing ones and adding WordsInterCappedLikeThis (a.k.a. CamelCase), which become links, which let you edit the newly instantiated pages.

That's it. But it's a bundle. The barriers to entry are almost nonexistent. You usually need a Web server to run the thing on, such as Apache or the Microsoft Internet Information Server (some are self-contained), and the users need browsers. For maintaining a set of interlinked text documents, it's hard to imagine anything simpler. At the upper end of the scale, you get MediaWiki, on which runs the Wikipedia, the free, user-authored encyclopedia containing half a million articles that is to wikis what Linux is to open source. Maintaining a MediaWiki is more complex than whacking the Edit This Page button, but gives a correspondingly longer feature list.

Wikitext and Engine Features
You might encounter the term wikitext. Don't be misled into thinking that it represents some kind of standard, as each wiki engine seems to sport its own idiosyncratic format. Let's pretend that Cunningham's c2 wiki is the standard to give us a baseline for our expectations. You can adorn text with horizontal rules by starting a line with four or more hyphens. You can construct a multilevel bulleted list by starting lines with one to four asterisks. Various levels of emphasis can be generated by surrounding with single-quote characters (see "Editing Wikitext"). To create a hyperlink within a wiki, use CamelCase; to link to the outside world, type the URL normally with the protocol specifier (for example, http://www.sdmagazine.com). Other engines support fancier formatting; for example, Cunningham has introduced table syntax in more recent versions.


[click for larger image]
Editing Wikitext
The standard page-edit function for a wiki: Open an HTML form with a text-edit box. Shown are a few wikitext formatting elements.

That's pretty much it. You can't wrap curved text around a Flash animation, but the resulting text is readable and the emphasis stays firmly on what you say, not how it looks. If you're thinking about a wiki for collaborative projects, here are some features to keep in mind. (The Wikipedia, recursively enough, suggests many of these at http://en.wikipedia.org/wiki/ Wiki_software; this page is also an excellent springboard for finding wiki engines.)

Consider features for writers and editors. Is the formatting language sufficiently powerful—conversely, is it simple enough for your user community? Can you insert images, or inline HTML text, or import HTML? How hard is it to customize the site's look and feel? Is there support for namespaces? (Otherwise, all links refer to the global "wiki space," so that two projects' pages, each containing a link to ProjectHistory, perforce point to the same page.) What collaborative mechanisms exist other than document edits—are there discussion or forum pages? How do users know when things change—does the engine support e-mail notification or RSS? What non-text files are supported? And, crucially, how easy is it to roll back unwanted changes?

Then you face application-level issues. Can you change wiki engines later, or is exporting to another text format too painful? (If worse comes to worst, you can always crawl the site, save the generated HTML and import it.) If you're supporting a small group of collaborators, you don't have to worry about scalability; if you anticipate heavy traffic, a database-backed engine will outperform file-based ones. Does the engine support any kind of user authentication? If you wish to restrict access to a limited set of users, can the Wiki engine accomplish this, or must you impose control via the Web browser? Finally, if you're experimenting, just how hard is it to bring the software up to speed? Here are a few representative wiki packages, with the strengths and weaknesses I encountered.



[click for larger image]
Editing MediaWiki
MediaWiki adds a few frills to the wikitext standard. Note the toolbar for formatting text, inserting adornments or inlining various media files.

Friki
Friki, or "Frank's Wiki," is a simple Java servlet-based wiki engine using files to represent its pages. Written by Frank Carver, it's an excellent way to dip a toe in the wiki waters if you already have a servlet container running. Installation instructions: Download friki.war to the webapps directory—done. It supports the "standard" wikitext format; rolling back pages is possible, though unobvious. An interesting quirk: clicking the Search button without entering any terms lists all pages in the wiki. Note that Friki requires that you're running at least Java 1.3.

 MediaWiki
The engine behind the Wikipedia, MediaWiki is implemented in PHP. Although some describe it as hard to install, I had it up and running in 20 minutes on a vanilla Fedora Core 3 system. (It's written for Linux, though in principle it should run on other platforms as well.) Its backing store is MySQL, so you can run industrial-strength sites on it. The formatting language uses square brackets for in-wiki links instead of CamelCase; the standard edit page provides a toolbar (see "Editing MediaWiki") for common functions, including embedding various media files. Namespaces are supported. Page rollback is simple, and a powerful set of administrative functions is available, though some require issuing queries directly to the database instead of being handled through the wiki itself. You can easily set MediaWiki up to allow changes from registered users only. Documentation is extensive, served through the wiki itself. The default look and feel is reasonably rich, professional and customizable (see "Sample Wikipedia Page"). MediaWiki supports forums, though not e-mail or RSS notification of changes.


[click for larger image]
Sample Wikipedia Page
The Wikipedia is the canonical example of what you can do with MediaWiki; here's the entry on data structures, with the navigation bar at the left and the toolbar on the top.

 

Perspective
If you're publishing with Microsoft Internet Information Server (IIS), especially collaborating with nonprogrammers, Perspective may be worth a try. This .NET-based wiki requires user authentication for editing (and can use Windows Integrated Authentication to do so), and supports a spiffy WYSIWYG editor (see "Perspective") in IE and Mozilla, obviating some of wikitext's more obscure corners. It also provides an RSS feed so that your team can keep apprised of changes.

FlexWiki
Another IIS-based product, FlexWiki offers a strong formatting language and some interesting desktop tool support. User authentication is required to change pages. FlexWiki adopts the novel approach of exposing the authoring API via Web services, letting developers craft authoring and maintenance tools that run on the desktop rather than in a browser using HTTP forms. The "native," browser-based authoring method is a flavor of wikitext; WYSIWYG editing tools for the desktop have been prototyped. FlexWiki supports e-mail RSS update feeds. FlexWiki and its support tools are under active development; expect them to improve and mature rapidly.

Wiki Woes
Of course, no technology is flawless. Wikis, designed for wide-open collaboration, show a few rough spots when adapted to software development.


[click for larger image]
Perspective
This wiki leverages Windows Forms to offer a nice WYSIWYG editor.

Vandals. Unless you're trying for the widest possible user community, it's best to hide your wiki behind some sort of access control. Otherwise, the maladjusted may take advantage of the Edit This Page button until you're ready to chuck the whole thing. A particularly annoying species of rodent adds his URL to your pages endlessly, trying to inflate his Google page rank. Some wikis allow user sign-ins, but enforcing a sign-in policy is against Wiki philosophy; most allow anonymous users to edit.

Yet Another Authoring Language. While some wikis let you embed HTML in their pages, most operate using their own—often idiosyncratic—markup language. Typing encoded text into an edit box and "compiling" it may seem natural to a programmer, but WYSIWYG editing would be a boon; HTML import eases the pain somewhat. As noted in "Wikitext and Engine Features," beware getting locked into a wikitext language that you may want to leave behind.

Looking for some alternatives to wikis? Consider:

Mailing lists. Nothing wrong with developing based on these, especially if you have a good threading mail client and some way to create searchable archives. E-mail is better at capturing the latest happening, though, than at maintaining documents. (If you've ever worked on something by e-mailing it successively to a set of collaborators, you've doubtless run into versioning nightmares that I need not belabor here.) You've got to have a server or service, but they're cheap to set up.

Off-the-shelf collaboration products. IBM Lotus Notes is the poster child here, and if you've got IT support to get it up and keep it going, a product like Notes can really lower the barriers for integrating personal-information-management administrivia (calendars, to-do lists) and shared document workspaces. SourceForge Enterprise (a finalist in this year's Jolt Awards) provides a full-on, on-site collaboration hub, with secure access, workflow and project management tools, and a central document code repository. Configuration management tools often cross over into this category, too; products such as Serena ChangeMan Dimensions or MKS Integrity are designed to be tailored to your workflow, and let you ensure that the right people get notified when a bug is fixed or a feature needs to be approved. But products such as Notes, Microsoft Exchange Server, Integrity or Dimensions aren't exactly "lightweight" in acquisition cost or upkeep and are a strategic commitment rather than an ad hoc solution. On the peer-to-peer side, Groove Networks' Virtual Office is a relatively inexpensive means of sharing artifacts and workspaces securely, with the additional benefit of intelligently handling synchronization of intermittently connected nodes. Macromedia's Contribute (another Jolt finalist) is almost Wiki-like, enabling easy editing and upload for collaborative websites. Most of these products provide SDKs if you need to add your own functionality.

Hosted forums and services. For low start-up overhead, it's tough to beat Yahoo Groupsy—you can have searchable message archives with optional e-mail notification, file upload space, polls, a calendar and even databases, and you can make a forum invitation-only. The only client-side tool needed is a browser (which will display a certain amount of inline advertising). No versioning of files, though, and you get only 20MB of space. And if what you're doing is proprietary, you'd better make the service provider sign a nondisclosure agreement (good luck). The other big player in this space is SourceForge's other face, SF.net, whose services are Web-based and suit publicly accessible, open source projects, with version control, bug tracking, forums, mailing lists and the like.

All these products and media have their place. But if you just want to get a collaborative document workspace up fast and spend as little time as possible maintaining it, the wiki world beckons.


New & Noteworthy Editor Rick Wayne has way too much fun with Web-enabled ecosystem management software for the University of Wisconsin. E-mail him at fewayne@facstaff.wisc.edu.


Related Reading


More Insights






Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

 
Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.
 
Dr. Dobb's TV