5 reasons wikis rock for documentation

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.

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.