Pros and cons of wikis for documentation

5 reasons wikis rock for documentation

Posted 01 Jun 2015 by 

up
55 readers like this
Typewriter keys
Image credits : 

Original photo by mshipp. Modified by Rikki Endsley. CC BY-SA 2.0.

You may not have noticed, but people often become attached to their favorite technology. This could be a mobile phone, a programming language, or a text editor. When you work on someone else's project, you generally have to go with whatever the prevailing tools and languages are, but when it's your own project, you get to choose the toys. Documentation requires technology, too, but most people have less of a pre-set opinion about documentation tooling than they do about web frameworks and version control systems. So how is a project to choose?

Wikis are a popular choice for many open source projects. Here are a few reasons why:

  1. Wikis offer a simple syntax. Contributors need to learn very little markup, and most wikis have a "formatting help" link for guidance. Formatting buttons on some wikis can mean zero manual markup.
  2. Wikis require no special tooling for contributors. All you need is a web browser. Whether you're working from a desktop or mobile device doesn't matter. With sufficient motivation, you might even be able to update content with cURL.
  3. Some project hosting sites include a wiki as part of the hosted offering. This means you can jump right in to writing content instead of standing up a server, creating the database, and so on.
  4. Wikis generally have version control built in. Need to roll back an edit? Just make a few clicks.
  5. Some wiki platforms have "talk" pages, allowing for meta discussion. This can be a really useful way to discuss changes to content in a way that's more constructive than warring edits.

Making the decision

Wikis aren't perfect, though. They're not well-suited for re-publishing in other formats or offline editing. Keeping the content organized such that it can be found easily can be challenging. Unorganized wikis are particularly prone to duplicated and stale content.

That's not to say your project shouldn't use a wiki. If you want contributions from many people—especially the less technical contributors—a wiki is a good choice. The Arch Linux project in particular has done an excellent job of using a wiki for documentation.

Wikis are well-suited to short posts about specific use cases. Someone looking for information about how to push a new git branch to a remote repository would probably find a one-paragraph wiki article more approachable than finding the information buried in a 50-page user guide.

Wikis can also be great for rapidly changing content—development planning, for example. If your project is young and hasn't stabilized yet, writing long-form documentation may not even be possible. The release notes for the Fedora project start out as wiki pages, which are later converted to a rendered markup language, combining the best of both worlds.

The best documentation is what actually gets written, so always favor a wiki over no documentation at all. Because the barrier to entry is so low, using a wiki can be a great way to get lots of content quickly. Just be prepared to tend the wiki garden.

Doc
Dish

This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us at open@opensource.com.

3 Comments

Hans Bezemer

You list 5 reasons why wikis are a popular choice. That's a different issue then you list in your title. I can't see why they "rock" - just pragmatic reasons why they're frequently chosen. I don't think they "rock". They're usually fragmented, doubled, not maintained.

Vote up!
0
Vote down!
0
wpg4665

You provide one option for documentation, and then talk about a "decision". Not much of a decision with only one option...why not provide alternatives. Also, there are different types of wiki's: DB backed wiki's tend to be the most common, there are so flat file wiki's, like Docuwiki, and other types I'm just not thinking of this early in the morning.

Vote up!
0
Vote down!
0
sethkenlon

A wiki should be a medium, not a style; a well-managed and maintained wiki can be great (like the Arch wiki, as noted in the article), but a poorly managed wiki usually crumbles into a useless, scattered, disjointed collection of outdated [dis-] information.

At least, that's what my experience has been.

Vote up!
0
Vote down!
0

Ben Cotton is a meteorologist by training and a high-performance computing engineer by trade. Ben works as a technical evangelist at Cycle Computing. He is a Fedora user and contributor, co-founded a local open source meetup group, and is a member of the Open Source Initiative and a supporter of Software Freedom Conservancy. Find him on Twitter (@FunnelFiasco) or at