// 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

10 Responses

Subscribe to comments with RSS.

  1. links for 2007-09-13 « Green Tea Ice Cream said, on September 13, 2007 at 4:34 am

    […] Do You Make These Mistakes with Wikis? 9 Ways To Build a Wiki That Doesn’t Suck « Internet Duct T…The Social Graph and Objects of Sociality – Bokardojill/txt » Web use and the Norwegian local electionsStarbucks and the SaudisMediaPost Publications – Yahoo, Bebo Cut An Ad Deal – 09/12/2007From The Magazine : Radar Online : Stoners vs. Six-Year-Olds […]

  2. Andy C said, on September 13, 2007 at 12:26 pm

    Engtech – an excellent, interesting and informative article. I am amazed it hasn’t provoked any comments.

    I was also taken with the concept of Wikis but really struggled with the dreaded WikiWord, editing content in general and importing existing data.

    I still have a TiddlyWiki (mainly because I loved the phrase ‘a reusable non-linear personal web notebook’) as a technical notebook on a USB stick. While I do like the audit trail and versioning in Wikis, I think that collaborative blogs might be better for projects.

  3. engtech said, on September 13, 2007 at 6:15 pm

    @Andy C:

    I’m thinking that the wiki communities don’t read blogs, and the blogging communities don’t read wikis :)

    Most of what I talked about is old news anyhow. A lot of wiki software does things correct out of the box. It’s only WikiWords that keep refusing to die the painful death it so richly deserves. They really do make things harder to manage.

  4. urbaneexistence said, on September 15, 2007 at 10:04 am

    I always thought it was the lack of WikiWords that made MediaWiki, and consequently Wikipedia, so much more popular than its predecessors. They are a terrible, terrible idea.

    Wikis, like anything else, can be right for the right type of content. Just like blogs, or Moodle, or even static pages. People need to start with content and ask themselves “What is the best format to present this content?” Not the other way around.

    I’m also surprised at the lack of comments; normally even the sanest critique of wikis provokes near-religious-fanatical response.

  5. engtech said, on September 16, 2007 at 12:20 am


    I agree 100% that you should pick the right tool for content. I’ve seen some really bad bastardizations on intranet wikis where they should have just put in a MySQL database and written a front end for data entry instead of using a wiki.

  6. […] is the only wiki with not just simple a WYSIWYG editor, but a full word processor that writes true html, not wiki syntax.  Beast?  I think the emphasis here will not be on the standalone product, but how well […]

  7. […] is the main trick in building a wiki: inspiring a community. Internet Duct Tape posted some great advice and observations on building a wiki community. Included in that was a table that related success with the size of […]

  8. Business Hacks mobile edition said, on December 11, 2007 at 6:00 pm

    […] important to pick the right one, and to manage it wisely. The blog Internet Duct Tape tells you how to keep your wiki from sucking, and the wizard at Wikimatrix lets you know what wiki you should use based on your project and the […]

  9. Pisedriendyex said, on January 12, 2009 at 7:20 pm

    http://www.twine.com/user/genericsone – animal sex stories ndijihe http://www.justin.tv/amandabe/profile – pamela anderson sex tape ncusgbt http://www.twine.com/user/ericcros – shemale sex iivxguq http://www.justin.tv/cristinamoll/profile – teen sex videos

  10. pfctdayelise said, on February 03, 2009 at 9:02 am

    Boo spam.

    Nice post. I agree with most of your points, but especially that wikis are poor at “exporting” information. As an example, MediaWiki provides feeds for very fine details (every single edit to a page, your watchlist, or the whole wiki), but there is no useful “summary” level view which would invite a once-a-month editor to drop by maybe once a week. Facebook and LinkedIn do this moderately well.

Comments are closed.

%d bloggers like this: