The Vicious Circle of Documentation

Posted: Sun, 15 February 2015 | permalink | 4 Comments

Ever worked at a company (or on a codebase, or whatever) where it seemed like, no matter what the question was, the answer was written down somewhere you could easily find it? Most people haven’t, sadly, but they do exist, and I can assure you that it is an absolute pleasure.

On the other hand, practically everyone has experienced completely undocumented systems and processes, where knowledge is shared by word-of-mouth, or lost every time someone quits.

Why are there so many more undocumented systems than documented ones out there, and how can we cause more well-documented systems to exist? The answer isn’t “people are lazy”, and the solution is simple – though not easy.

Why Johnny Doesn’t Read

When someone needs to know something, they might go look for some documentation, or they might ask someone else or just guess wildly. The behaviour “look for documentation” is often reinforced negatively, by the result “documentation doesn’t exist”.

At the same time, the behaviours “ask someone” and “guess wildly” are positively reinforced, by the results “I get my question answered” and/or “at least I can get on with my work”. Over time, people optimise their behaviour by skipping the “look for documentation” step, and just go straight to asking other people (or guessing wildly).

Why Johnny Doesn’t Write

When someone writes documentation, they’re hoping that people will read it and not have to ask them questions in order to be productive and do the right thing. Hence, the behaviour “write documentation” is negatively reinforced by the results “I still get asked questions”, and “nobody does things the right way around here, dammit!”

Worse, though, is that there is very little positive reinforcement for the author: when someone does read the docs, and thus doesn’t ask a question, the author almost certainly doesn’t know they dodged a bullet. Similarly, when someone does things the right way, it’s unlikely that anyone will notice. It’s only the mistakes that catch the attention.

Given that the experience of writing documentation tends to skew towards the negative, it’s not surprising that eventually, the time spent writing documentation is reallocated to other, more utility-producing activities.

Death Spiral

The combination of these two situations is self-reinforcing. While a suitably motivated reader might start by strictly looking for documentation, or an author initially be enthused to always fully documenting their work, over time the “reflex” will be for readers to just go ask someone, because “there’s never any documentation!”, and for authors to not write documentation because “nobody bothers to read what I write anyway!”.

It is important to recognise that this iterative feedback loop is the “natural state” of the reader/author ecosystem, resulting in something akin to thermodynamic entropy. To avoid the system descending into chaos, energy needs to be constantly applied to keep the system in order.

The Solution

Effective methods for avoiding the vicious circle can be derived from the things that cause it. Change the forces that apply themselves to readers and authors, and they will behave differently.

On the reader’s side, the most effective way to encourage people to read documentation is for it to consistently exist. This means that those in control of a project or system mustn’t consider something “done” until the documentation is in a good state. Patches shouldn’t be landed, and releases shouldn’t be made, unless the documentation is altered to match the functional changes being made. Yes, this requires discipline, which is just a form of energy application to prevent entropic decay.

Writing documentation should be an explicit and well-understood part of somebody’s job description. Whoever is responsible for documentation needs to be given the time to do it properly. Writing well takes time and mental energy, and that time needs to be factored into the plans. Never forget that skimping on documentation, like short-changing QA or customer support, is a false economy that will cost more in the long term than it saves in the short term.

Even if the documentation exists, though, some people are going to tend towards asking people rather than consulting the documentation. This isn’t a moral failing on their part, but only happens when they believe that asking someone is more beneficial to them than going to the documentation. To change the behaviour, you need to change the belief.

You could change the belief by increasing the “cost” of asking. You could fire (or hellban) anyone who ever asks a question that is answered in the documentation. But you shouldn’t. You could yell “RTFM!” at everyone who asks a question. Thankfully that’s one acronym that’s falling out of favour.

Alternately, you can reduce the “cost” of getting the answer from the documentation. Possibly the largest single productivity boost for programmers, for example, has been the existence of Google. Whatever your problem, there’s a pretty good chance that a search or two will find a solution. For your private documentation, you probably don’t have the power of Google available, but decent full-text search systems are available. Use them.

Finally, authors would benefit from more positive reinforcement. If you find good documentation, let the author know! It requires a lot of effort (comparatively) to look up an author’s contact details and send them a nice e-mail. The “like” button is a more low-energy way of achieving a similar outcome – you click the button, and the author gets a warm, fuzzy feeling. If your internal documentation system doesn’t have some way to “close the loop” and let readers easily give authors a bit of kudos, fix it so it does.

Heck, even if authors just know that a page they wrote was loaded N times in the past week, that’s better than the current situation, in which deafening silence persists, punctuated by the occasional plaintive cry of “Hey, do you know how to…?”.

Do you have any other ideas for how to encourage readers to read, and for authors to write?


From: niq
2015-02-15 20:50

There’s an opposite face of documentation. Namely, someone produces it, then the system documented changes but the documentation lives on. Practices that were right for 1995 become magical incantations in 2015, fossilised in 1000 long-forgotten (except by google) tutorials that copied a recipe that was originally an ugly hack to work around a long-since-fixed defect.

Deeply thought through documentation - at the level of a decent book - can have a longer shelf life. Up to a point! One solution that helps is for communities to value contributors to their documentation at the same level as those who code. Of course some do both, but if you hack you’re continually up against a dilemma: when you think about something deeply enough to document it, you naturally see how to improve it. Can you resist doing that before documenting the unimproved version? OK, now you’ve patched it you find another issue, and the docs get pushed back again!

Low-level doxygen-style stuff is always good: it’s useful, and low effort to maintain. But for higher-level stuff, both google and just-ask will surely remain essential tools.

More of my thoughts on the subject at

From: dredmorbius
2015-02-16 16:38

A few comments:

  • Responding to support requests with the specific and relevant docs is quite useful. It reduces your workload, allows you to vet that the docs exist, and publicizes them.

  • From the HN discussion: having a comprehensive internal search utility which can scan multiple document formats (HTML, PDF, ePub, Word, Excel, Powerpoint, etc.) is highly useful.

  • Use tools that allow for eBook outputs. Today, with Pandoc, that’s pretty much anything, but having docs that you can export to ePub and carry on a tablet or eBook reader are a lifesaver. Getting the update schedule worked out may take some doing but for Ops and Eng work, I’d make this a mandate.

From: Justin Andrusk
2015-02-17 10:53

For me refusing to answer questions covered in the documentation. keep sending them links til they stop bothering you.

From: Andrew
2015-03-10 20:41

Like!!, Did I say that already? Yeahh , this is really pretty much of what I like right now, so I want to give you some Feedback, hope my comment will not be roboted by the evil forces out there, I wrote it manually, and I want humen readers, if any. Maybe you are wrong patially, some people might not write any docs because the don’t want to be docs. It is kind of frustrating, comletely dissatisfying, when, actually you would be a doctor already in the Windows-world, but, well you are in the Linux-world, thus you sit at home at your own desk and can’t even find any paid job, say for three years, plus. Also you don’t only want to ba a doc, you also don’t want to produce content for other docs and professors to spend their time reading your documentation. If they are really interested in things and how stuff works, they can still read the source code, maybe in some cases well-commented source-code can be more informative and instructive, than any text-only-documentation might be. So in my opinion, not everyone needs to write separate text-documentation, especially, when they are not paid for doing so. Maybe you are the guy, that writes the tool, that extracts comments from source-code in order to produce some generic text-only documntation for those, who say, ‘code really makes my eyes bleed (or my finger tips), I absolutely can’t stand it’.

Post a comment

All comments are held for moderation; markdown formatting accepted.

This is a honeypot form. Do not use this form unless you want to get your IP address blacklisted. Use the second form below for comments.
Name: (required)
E-mail: (required, not published)
Website: (optional)
Name: (required)
E-mail: (required, not published)
Website: (optional)