// Internet Duct Tape

Do You Make These Mistakes with Wikis? 9 Ways To Build a Wiki That Doesn’t Suck

Posted in Technology, Wikipedia, Writing Better Documentation by engtech on September 12, 2007

Wikipedia and Wikis

There’s something about the hint of fall in the air that has always appealed to me. It’s my favorite time of the year, and as the seasons change I find the motivation to apply change to my own life. Last month I had the epiphany that I’ve been far too busy and I need to get a handle on the way I spend my time. The Internet is buzzing about using David Allen’s Getting to Done system to be more productive. There are a hundred and one different software tools you can use with the system; for the past week I’ve been using a personal wiki software called d-cubed/d3 gtd to do it.

Astute readers may guess from the title that there’s a rant coming up, and I want to prefix to say that I have nothing against d-cubed/d3 gtd. It’s good software. I respect Tom, the guy who built it, and appreciate what he’s done and how he’s been available for help. I’m still using and enjoying d-cubed/d3 gtd. No, my beef is with the entire foundation behind d3: that dark Hawaiian voodoo called wiki.

What Is a Wiki?

“Wiki is a piece of server software that allows users to freely create and edit Web page content using any Web browser. Wiki supports hyperlinks and has a simple text syntax for creating new pages and crosslinks between internal pages on the fly.

Wiki is unusual among group communication mechanisms in that it allows the organization of contributions to be edited in addition to the content itself.

Like many simple concepts, “open editing” has some profound and subtle effects on Wiki usage. Allowing everyday users to create and edit any page in a Web site is exciting in that it encourages democratic use of the Web and promotes content composition by nontechnical users.” — Ward Cunningham, creator of Wikis

The first time I saw a wiki was in 1996 and I remember being struck by two distinct thoughts: “wow, that’s ugly” and “why would I want to let people edit what I write?” Fast forward eleven years later and one of the most popular sites on the Internet is Wikipedia, a publicly editable encyclopedia. My uncanny ability to predict what’s going to become widely popular explains why my stock portfolio is doing to badly (damn you, Microsoft Zune).

This video from CommonCraft does a very good job of explaining what Wikis are good for. The wonderful thing about wikis is that wikis are wonderful let you quickly edit a web page and let more than one person collaborate on a document.

You might recognize that video from a post I wrote on LorelleOnWordPress that includes other videos that explain RSS, Social Networks, and Social Bookmarking. How Stuff Works gives even more information about how wikis work and what they are good for.

Wikis in Practice

The two strongest features of a wiki is that 1) anyone can edit a page and 2) it is quick to do an edit. Put those together and the power of a wiki is that they make it trivial to correct mistakes in the current document you are viewing. Wikipedia shows the power of collaborative editing — what is hidden is the massive effort and time sink that people put into it.

“With enough eyes all bugs are shallow.” But any programmer can tell you that a project with poor communication between different contributors always turns into SNAFU. There is great benefit to having many people improving a document through collaborative editing, but not if they aren’t all heading towards the same final result.

Photo by gadl

Small Scale Wiki Personal or a small group of people Works well
Medium Scale Wiki 10s of people Can grow out of control if there isn’t a clear vision and people don’t own things
Large Scale Wiki 100s or 1000s of people Usually a public wiki where some contributors are actively acting against the best interests of the wiki
Massive Scale Wiki 10000s of people Works well because there are enough contributors to handle the massive amount of work involved

I’m not an expert on wikis by any means, but I have used PBWiki, TWiki, TiddlyWiki and Wikipedia before. I’ve used wikis in multiple contexts from personal information storing, to corporate intranet backbone to internet social software. Wikis seem to work best on the small scale and massive scale. It’s in the middle with a medium/large number of collaborators information gets confusing. Like some plants, wikis tend to grow the same way no matter who is building them. Wikis grow wide and shallow, not narrow and deep. This makes them perfect for something like a dictionary or encyclopedia, but not as good for document tracking on an Intranet. Wikis favour a large number of pages at the same level instead of a tree hierarchy.

Creating a wiki is a grassroots process.

How Wikis Should Be Organized

  • Administration
    • Forms
    • Time Tracking
    • Vacations
  • Engineering
    • Project1
      • Design
        • Product Spec
      • Verification
        • Verification Spec
        • Verification Environment
        • Verification Plan
        • Regression Results
      • Validation
    • Project2
  • Manufacturing

What Wikis Really Grow Into

  • Administration
    • Forms
    • Time Tracking
    • Vacations
    • Phone Numbers
    • Board Room Booking
  • Engineering
    • Project1
    • Design
      • Product Spec
    • Verification
      • Verification Spec
      • Verification Environment
      • Verification Plan
      • Verification Review Minutes
      • Action Items from Friday’s Review
      • How to Run a Test
      • Lab Tracking
      • Regression Results
      • Validation
    • Project2
  • Manufacturing

Wikis tend to spread out wide rather than have a strict hierarchy — and this can make it very hard to find what you’re looking for.

“Wikis are great for ad-hoc arrangement and re-arrangement of data, but they don’t respect existing data. And with 2-million-plus documents in dozens of formats sitting in our document management system, we need to respect existing data. Wikis will be useful to the extent they enable us to re-use, remix, reorganize, review, and extend those documents. What is needed is a wiki that is created, edited, and saved in Word.”

Why Do Wikis Suck?

If you aren’t familiar with wiki software (and you’re still reading?!) you should skip this section. I’m not talking about a specific wiki implementation, but general wikisms I’ve noticed in the various wiki software I’ve tried. If your WikiFlavour doesn’t have these problems then give yourself a pat on the back because you dodged a bullet.

The inventor of WikiWords should be shot

  • I understand that the core of wikis is that they can be quickly edited but creating links haphazardly is the primary reason why wikis grow like weeds instead of carefully tended gardens.
  • Having non-standard capitalization (CamelCase) automatically links to another page on the Wiki is only useful approximately 10% of the time.
  • The other 90% of the time you have to go back and re-edit a page to remove unintentional WikiWord links.
  • It promotes writing everything in lowercase to avoid the unintentional creation of WikiWords.
    CamelCase is the dumbest linking structure ever invented. Even the Wiki page on Wikipedia agrees with me:

    “Originally, most wikis used CamelCase when naming program identifiers. These are produced by capitalizing words in a phrase and removing the spaces between them (the word “CamelCase” is itself an example). While CamelCase makes linking very easy, it also leads to links which are written in a form that deviates from the standard spelling. … There is no easy way to determine which capital letters should remain capitalized. As a result, many wikis now have “free linking” using brackets, and some disable CamelCase by default.”

Wiki syntax reinvents the wheel

  • Wiki software uses its own syntax for formatting text in an effort to be more human readable than HTML.
  • Wiki syntax succeeds in being more concise than HTML, but more often than this means your normal punctuation or capitalization is being misinterpreted as wiki syntax.
  • Non-standard — different Wiki software uses different syntax.
  • Is learning wiki syntax really easier than HTML? <b>bold</b> is easier to remember than ”bold”.
  • WYSIWYG HTML editors are a solved problem thanks to software like TinyMCE — using wiki syntax is much more complicated then learning a WYSIWYG editor that essentially works like every other wordprocessing software you’ve ever used.
  • If I don’t like having to learn a non-standard formatting syntax when switch between 3-5 different programming languages on a weekly basis, then how do normal people feel about it?

Wikis create an information sink-hole

  • It is hard to import information into a wiki from other sources.
  • It is hard to export information out of wikis (eg: RSS feeds).
  • Wiki data remains stationary, when users want filtered data moving at them via email or RSS.
  • Where’s the API? Wikis are intended to make it “easier for humans to edit” documents, but corporate wikis can benefit from automation like updating a report or a log on the wiki instead of sending updates by email. Wikis need an API so that it is easy to create scripts to add or edit pages on a Wiki.

Large scale wikis become chaotic and disorganized

  • Multiple collaboration means no one owns anything — organization comes from someone having a vested interest to organize and maintain.
  • Information is hard to navigate consistently because there is no unifying vision to the structure.
  • Large scale wikis turn into a flat hierarchy of documents with no hierarchy.

Having multiple editors *requires* tracking changes

  • With multiple editors on a document, version control and discussion of changes become essential requirements.
  • All changes should be saved and easily backed out of.
  • Need the ability to protect pages (lock) from edits.

Wikis and Search

  • Using WikiWords as titles makes it near impossible to build a decent search system. Wikis usually generate overly concise URLs or incomprehensible URLs with no meaning.
    • Always have to click on search results to see what the document really is because the title isn’t descriptive enough.
    • The default search results are usually “what search found first” with no attempt to sort by relevance.
    • If I’ve learned anything from GMail it’s the power of search+tags. So the problem with finding information in a Wiki is really a problem with search.
  • Search isn’t as big a problem with publicly accessible wikis because you can use Google. It is a much bigger problem with personal/intranet wikis. Data goes into the wiki but good luck EVER finding it again.
  • The ability to “Jump” to a specific WikiWord is
    • usually misinterpreted as a search form
    • encourages the use of short WikiWords that makes a large scale wiki more of a mess
    • is sometimes case sensitive which adds much more complexity than entering search terms for a specific document


  • Many wikis offer plugins for adding additional functionality.
  • Adding plugins creates another layer of complexity and potential conflicts with upgrading the core software.
  • Developing custom plugins can be a huge time sink — it’s nice to have the ability to do so, but it should be a last resort.
  • Dependence on plugins can create chicken-and-egg scenarios that complicate upgrading the wiki software.

Plugins that greatly improve the wiki software’s functionality should always *become* core functionality. This is a classic problem with all software that supports plugins — at some point they need to be packaged together into a distribution so that the majority of users can appreciate them instead of living in the dark age.

Building Wiki Software That Doesn’t Suck

You know what a wiki is, you know why wikis end up sucking, and if you’re still reading this far then you’ve probably used a wiki yourself. Some wiki software gets it right, but unfortunately the core distributions of many WikiFlavours are still missing some of these essential features. This is a list of what I think *every* wiki software should do to improve the WikiExperience for everyone.

1. Make It Simple to Edit, Not Just Quick to Edit

1.1 Disable WikiWords and CamelCase

Users have to create links by hand instead of unintentionally creating links because of capitalization. It will lead to meaningful document titles with headings longer than JimsListOfBugs.

1.2 WYSIWYG text editor

Let Ctrl-B bold the selected text! Contributors should not have to write in all lowercase with no punctuation in constant fear of accidentally embedding wiki syntax.

2. Help Me Find What I’m Looking For

2.1 Indexed search that orders by relevance

I’ve mentioned before that wikis need to build meaningful URLs that are human readable. They also should be able to rank pages based on what links to it, and to do something smart like click tracking where if I always click on result #6 when I search for product plan then MAYBE it should be one of the first results.

2.2 Navigation clues

Wikis need to support effective navigation with good titles, breadcrumbs, and easily created tables of contents. When I’m looking at a page I should be able to easily the parent hierarchy and child pages, as well as neighbouring pages.

3. Never Lose Data

3.1 Store and track changes

Wikis need version control for every change and easy rollback for all edits. Users need to have notification, watchlists, and easy changelogs. This is mostly a solved problem to various degrees, but it’s still surprising that some personal wiki software doesn’t support this.

3.2 Refactoring

I’ve said that wikis grow like weeds and that need a gardener to prune them. Refactoring and reorganizing pages needs to be simple to do and well supported. Information should be easy to move and automatically leave a forwarding address behind.

3.3 Discussions

Each page on the wiki needs to have a behind the scenes discussion page where direction can be agreed on, differences can be debated and issues can be captured in a message board / forum format.

4. Getting Data In and Out

4.1 Document management

People are going to want to attach all kinds of documents to wikis: from office documents like pdf, doc and xls, to traditional media files like images and video. These attachments should be treated the same as wiki pages when it comes to search and version control.

4.2 Wikis need APIs for in/out

One of the things people often complain about is importing/exporting data from a wiki. They’re meant to be easily human editable, but for some reason they overlook that you likely have a existing information in another format that you want to merge in and retain as much formatting/linking as possible. If there is an easy-to-use API then data can be moved around by writing scripts.


Wikis are very powerful when used correctly, but unfortunately there are 51 flavours of wikis and what has become best practice in advanced wiki software can seem painful archaic in software that still follows in the footsteps of the WorldWideWiki. Yes, I’m looking at you WikiWords. Wikis are becoming the defacto standard for modern corporate intranets, while they are undoubtedly better than the static and out of date web sites that existed before the still have a long way to go in some areas where intranets have always been weak — namely search.

Any day now Google will be opening up registration for it’s JotSpot wiki software. It’ll be interesting to see if they can get over their product schizophrenia and intelligently integrate wikis with wordprocessing, spreadsheets, slides, blogs, email, calendar, rss readers and build an intranet solution that far outclasses anything currently available. They have all the pieces, and the killer knowledge that everyone is missing — how to build an intranet search that works over all the formats.

It’s sad that downloading documents from the corporate intranet and using Google Desktop search is still 95 times more effective than using intranet search.

Links You Can Use

Related Posts

Wikipedia Loses the Google Juice

Posted in Technology, Wikipedia by engtech on January 23, 2007

Additional coverage: Official site, TechMeme, Nick Carr, Blogoscope, Search Engine Journal, Digital Inspiration, Seth Finklestein,On Going

Wikipedia is the online encyclopedia that anyone can contribute to (although your contributions are likely to be deleted). It is also one of the most linked to sites in the world. Quite often it shows up in the top ten results on Google. When I first started blogging I saw Wikipedia as an “open directory” instead of an encyclopedia and I was guilty of injecting links to my articles if I thought they were relevant (aka “blog spam”).

Wikipedia is a trusted resource and it is commonly used to define terms or provide additional information. It has a large audience, a lot of traffic, is very trusted by search engines, and anyone can easily edit a page and inject a link. This makes it a huge target. I’m not the only one who thought this. It’s hard to surf through Wikipedia without finding a questionable link or two. Today, Wikipedia is finally taking a stance on spam and they’ve decided to deter spammers by using the rel=”nofollow” tag on all external links.


On Wikipedia, Blogging and the Anti-blog Bias

Posted in Becoming a Better Blogger, Technology, Wikipedia by engtech on December 05, 2006

(hat tip to Nicholas Carr who writes about Wikipedia quite often)

When every blogger first starts out they get the bright idea to add links to their articles on Wikipedia, treating it as a public directory instead of an authoritative resource. Adding links to blogs is very much considered inappropriate behaviour, and they will track down any other edits you’ve ever made and go through them with a fine-toothed comb. It doesn’t matter if you add relevant content to the discussion, or you are the only other source of discussion on the subject: you’ll get hit as part of the anti-blog bias.

Wikipedia has a hate on for blogs, and it’s understandable when seeing things from their point of view. A popular article like the Google page must get hundreds of ego-motivated modifications as people try to add their article on Google (I was guilty of trying to add my article on Google Code Project Hosting). Imagine if everyone who has ever written a book or movie review tried to add a link to their blog post. With “55 million blogs in the blogosphere” it is no surprise that there is a lock-down on blog links. This anti-blog slant also carries over to Wikipedia bio pages on bloggers.



Get every new post delivered to your Inbox.

Join 281 other followers