Wiki considered harmful for documentation

TL;DR: as a means of internal technical documentation, wiki is inconsistent, misleading, and unmaintainable. Migrate documentation from wiki to a source-control form as soon as you have customers, if you care about quality and productivity.

To be fair, wiki has its place.

At a very early stage of your company/project, you just need a place to dump and share notes. Things are changing so rapidly that any effort on polishing the documentation would seem ridiculously misplaced: why bother making something look good if it’s to be replaced tomorrow?

Wiki fits the bill perfectly well here: anyone, at any time, can add/update/delete documentation with zero friction. The machine is optimized for speed. If a mistake is made, chances are it won’t affect many people (given it’s early stage), and anyone else could fix it when they notice it.

Yet start-ups become grown-ups. Prototypes become real products. Information in wiki becomes misinformation.

Many times I’ve seen in wiki contradicting information (because anyone can edit it without a review), out-dated information (because the developers don’t remember to update it), personal opinions posed as rules/guidelines (again, because anyone can edit it), and poor presentation (bad formatting, typos, grammar mistakes, etc - because the changes are not reviewed).

Yet often I’m afraid to fix the mistakes as I don’t know why the original authors wrote what they wrote (because there is little metadata on the changes) and I fear I might be making a bigger mistake by “fixing their mistake”.

To make things worse, the same thing may be presented in many places, inconsistently (because anyone can start a new wiki page). It’s impossible to find all the places that mention something and fix them all when the thing has changed.

As a result, information in wiki quickly becomes untrustworthy, confusing, and misleading.

My rule of thumb: once your system has customers outside of your immediate team, it’s time to move away from wiki as fast as you can.

Where to? You might ask.

The ideal medium should satisfy several requirements:

1. It should be version controlled, so that each change leaves a trace on who made it, why they made it, and what the change is. It follows that the format should be easily diffable.
2. Changes should be reviewed, so that personal opinions and mistakes don’t creep into the documentation easily.
3. It should sit next to the code, so that a code search of a concept will reveal both its implementation and its documentation. This is how we don’t forget to keep the two in agreement.

Documentation written in Markdown and checked into the code repository is a good solution. The two companies I have worked at recently have both adopted such technologies. With this set-up,

• Each project puts its documentation in a bunch of .md files that are easily editable.
• The .md files are automatically rendered into HTML for easy viewing.
• All changes are reviewed per the company’s code review policy. Random opinions and poor writing become much more rare.
• Change descriptions record the motivation of the changes so that future readers and maintainers can easily understand the real intentions of the original authors (obviously we also need to enforce change description best practices).
• When a developer changes the code, they can easily find documentation that references the code and update it at the same time.

As a result, documentation becomes fresher, better written, more consistent, and more correct.

Wouldn’t this increase the barrier for documentation improvements and lead to fewer people motivated to contribute? Knowledge is created at an alarming speed, so how can the process keep up with the rate of change? Some may ask.

My answer is that if a company has a healthy code review culture (e.g. reviewers strive to do a good job and keep the turn-around time low), the process really doesn’t add that much friction and its benefit is tremendous. Also, I’m not proposing to put all information into the repository - for sharing knowledge that’s more dynamic, we have complementary tools like Slack, Discord, and etc. We just don’t want to rely on wiki as a primary medium for important information that many co-workers depend on.

What’s your take on this subject? Please share in the comments!