Choosing between wiki- and git-based documentation

A common decision that comes up in open source projects is choosing a platform for documentation. Broadly speaking, the two most common choices are a wiki and a set of text files hosted in a git repo and published by some rendering tool. MediaWiki, which powers Wikipedia, is the best-known wiki example. The git-based option has a variety of options in each step. reStructured Text rendered by Sphinx and published to Read the Docs is a representative example.

I suspect most projects don’t put a lot of thought into the initial decision. Once they’ve lived with the first choice for a while, they start looking for better options. The two big problems that need to be solved are out of date information and too few contributors.

Wikis have a reputation for out of date information — a friend says “wiki” stands for “where information kills itself”. But “the information is out of date” is a process problem, not a technical problem. Docs need to be actively curated (“gardening” is a term I like here), regardless of what platform they’re on. A wiki is more accessible, which helps get more people involved, but the workflow is worse. It’s not that “a git-based workflow is more familiar to developers”, it’s that the editorial workflow is bad on a wiki.

In a wiki, either people can edit the page or they can’t. This leads to one of two opposite outcomes: 1. they make big edits without talking to anyone which makes relying on the wiki for authoritative info risky. 2. people are afraid to make minor edits because they don’t want to break anything.

git-based docs allow anyone* to submit a proposal by way of a pull request. Then the trusted contributors can work with them to refine it if needed. It also allows trusted contributors to make a proposal for broader comment. This workflow improves the overall collaboration in the project’s documentation, even though it comes with a steeper learning curve.

Spam negates the wiki’s lower barrier to entry anyway. Any website that allows content submission will be a target for spam. A well-known project’s wiki is a particularly attractive target. This means you have to put barriers in place to prevent (at least some) vandalism.

My recommendation, when I’m asked, is to go with a git-based documentation system. Of course, you have to choose what’s best for your project.

This post comes from my comment on Allan Day’s “What to do with the GNOME wiki?” post.

This post’s featured photo by Sincerely Media on Unsplash.