“But I’ll remember it!” — why people don’t write documentation

By August 10, 2009Technical

As I mentioned in my last documentation-related article, having a wiki or other documentation repository is really only a small part of the system documentation battle. What really counts is actually getting it chock full of all the knowledge in your organisation, and — possibly even more importantly — keeping it up-to-date forever and ever, Amen.

Just telling people to document their work really doesn’t work. While a quick “hey everyone, write some docs!” might get a desultory page or two written, it’s not really enough. Writing things down needs to be as natural as breathing, and about as easy. In fact, you should really aim for it to be easier to write than to not write, so that the “natural” choice is to do it.

Finding and eliminating the things that prevent people from writing documentation is the key. Every barrier to writing a good, solid document that you can remove means that much more documentation can be written. While I’m sure there are a million possible reasons “why not”, here are a few that I’ve noticed (usually in myself), and how I go about dealing with them.

  • They don’t feel they have to. Sure, there aren’t many people who would answer a confident “no” to the question “Do you need to document any of your work?”, but that’s different to it feeling wrong not to document things. Encouraging a culture of documenting things, so that any lack of documentation feels wrong at a gut level, is a crucial part of getting documentation written.Please note that when say “feels wrong”, I don’t mean that it feels illegal or naughty — that way lies guilt and recriminations and every other kind of organisational unpleasantness. No, what I mean is that you feel uneasy about something until it’s been documented — like leaving the milk out on the bench. You just don’t feel right until it’s back in the fridge. (Well, OK, maybe that’s just me, but you get the point).
  • I’ll remember it“: Yeah, sure you will. Whilst there are people who have an eidetic memory, they’re rare enough that it’s unlikely any of them work on your team. What’s more, even if you have someone like this, not everyone is so gifted, and an eidetic memory still doesn’t confer telepathic ability, so communication is still required.People who argue against the need to document just need to be talked down from their suicide pact. Pair them with someone who likes documenting, build a documentation culture, and let them experience how much better it is when things are written down.
  • They think they suck at it. Very few people like to do things they’re not good at, and writing docs is no exception. It’s true that some people really do suck at writing, and those people need to be trained to improve their skills, but far more people can do it, they just don’t think they can. Gentle encouragement, pairing with someone who does know they’re good at writing, along with removing the other blockers (so that people start trying it and realising they’re good at it) will solve much of this problem.
  • I don’t know where to put this where people will find it. I can strongly relate to this sentiment, as it’s one of the most common reasons I give to myself for why I don’t document things sometimes. Ultimately, what I think any rapidly changing wiki needs is a librarian — someone who makes it their responsibility to keep all the information organised. I can imagine that a large enough organisation might have a literal librarian (someone trained in information collection and management), but almost everyone doesn’t have that much stuff. Instead, there just needs to be someone who knows that they’re responsible for keeping an eye on the clutter, and everyone else needs to know who the librarian is, too, so they know who to talk to about their categorisation woes.I would say that a project manager with a strong technical background is the best person to act as librarian (non-technical project managers, whilst being a bad idea in general unless there’s a strong technical lead, are especially bad in this case because they lack the experience to know how most of the documentation will be used, and hence can’t arrange it properly). They should have the “high level” view necessary to keep classification and arrangement logically sensible, without getting bogged down in the minutiae of one little corner of the world.

    Rotating the job of librarian around the team doesn’t work, as what’s really happening when someone is arranging everything is that the content is being organised in a way that is most logical to the librarian, and then everyone else just starts to learn to think like that person when it comes to finding the information again. Changing who does the job regularly doesn’t allow any of that to happen, and everything falls apart.

  • I don’t know what to write. We’ve all been there: the horror of writer’s block. The techniques for overcoming this are many, varied, and are learnt over time as you write more. Pairing, good team support, and experience are the keys to overcoming this problem.
  • Not knowing who to write for. This comes down to knowing how to write, but it’s worth making as a separate point. Before you start writing anything, decide who should be reading this and more importantly why they’re reading it. This will help ensure the correct tone, level of detail, and document structure. Describing the architecture of the system is a whole different style of writing from giving a procedure to resuscitate the app server in a real big hurry when it fails, and it’s important to get the tone right, otherwise your document is going to be pretty un-useful.
  • Nobody will ever read it anyway. In my pre-document-everything days, this was my go-to excuse. I couldn’t count how many times I used it. It can even be true, sometimes — if someone’s come up empty every time they looked for docs, pretty soon they stop searching. The best way to avoid this feeling is to not let it grow, but if you’re already in this situation, you need to work at reversing the impression.

    The only way to get people back into the habit of looking for and reading documentation is to make them explicitly aware that it exists, and that reading it will solve their problem quicker than interrupting someone else and asking them. This means that your documentation must be easily discoverable (good searching, good indexing), the docs in there must be high quality (constant QA), and it must be very likely that the answer is actually in there (keeping documentation up to date).

    On a closely related point, if you’ve got any external systems that tell you to do things, ensure that they provide easy pointers to relevant documentation. For example, your monitoring system should provide links to wiki pages describing how to diagnose and fix each individual problem (so e-mail alerts for the “Is the primary website up?” check should link to a procedure titled “how to restart the primary website when it fails”).

    As a more concrete example, we’ve got an automated event handler that resizes disk partitions for customer backups when they start to fill up. When that handler fires, it creates a ticket describing who was resized, and provides a direct link to the procedure for updating billing records. Nobody ever has any excuse not to follow the procedure, and they’re constantly reminded of the presence of a huge swathe of useful documentation on how to do their jobs.

  • If I write stuff down, you can outsource my job / fire me! If you really are just getting documentation written so you can outsource their jobs, then you’re evil and can get stuffed. If your corporate culture is such that people are legitimately worried about this, you’ve got bigger, more toxic problems than a lack of documentation. On the other hand, if it’s just rampant paranoia, I suggest that perhaps a psychiatric assessment might be of assistance.
  • I don’t have time now, I’ll do it later. To this, I say: “Yes, you do” and “No, I’m pretty sure you won’t”. Documentation, like automated testing, is a dish best served with the main course, not for dessert. Budget time in your project plans for documentation, and make sure everyone knows it. Make reviewing the documentation part of the review, and be generous with people who slip the timeline due to documentation work.A closely related problem is getting dragged off to do something else as soon as the “real job” is done, without having done the documentation. To combat this, everyone needs to know that “the job’s not done ’til the wiki’s up-to-date”, staff must have the authority to say “I can’t do that other task, because I haven’t finished documenting this yet”, and management needs to learn to stop judging completion by when the service is working, but rather by when it’s documented.

Ultimately, the best way to get documentation written is to make the writing a natural a part of the workflow, like logging into your workstation when you start work. Some of the ways I think work well to move everyone in the right direction include:

  • When new team members come on board, take the time to give them a guided tour of your existing documentation. Sure, these days most technical people already know what a wiki is and how to do the basics, but everyone structures their wiki content differently, and different wiki engines encourage different behaviour. Give the new geek a strong impression of how good your docs are, so they’ll be encouraged right from the start to keep that tradition going, and give them an idea of how the wiki is structured and how to find information so that their early experiences aren’t frustrating.
  • Answer all questions with a wiki page — either point someone to an existing page, or write a new one and point them at that. This can be slow and tedious at first if you’ve got a huge, undocumented mess, and might have to be applied selectively at first, but communicating through the wiki both ensures that documentation gets written, and that everyone gets into the habit of using the wiki to find the answers to their problems.As an aside, the person answering the question should be writing the page, instead of the questioner getting a verbal answer and then writing things down. Whilst this undoubtedly takes more time, it means that people can’t get away with skimping on their docs and then expecting the new guys to take up the slack, and the person asking the question is unlikely to have sufficient visibility into the problem to structure a page appropriately. Also, having someone write a page (to answer the question) and then someone else immediately read it to get the answer, provides a simple informal QA mechanism.
  • In your project plans, explicitly describe the documentation to be written for every single step. (You do have project plans, don’t you?) This isn’t just adding “Document as needed” to the end of each item description; that’s no where near detailed enough. Instead, write things like “Setup an internal package repository to contain all of the cluster-specific packages. Document how to build new packages, update existing packages (both existing-internal and newly-modified-from-upstream packages), and how to upload built packages to the repository and rebuild the indexes at Procedures/PackageManagement”.Yes, most of that description covers the docs rather than the core point, but that’s OK (and intentional) — it’s far more likely that whoever gets assigned that task will know how to setup a package repository and can judge when it’s done; far less likely is that they’re going to automatically think of all the possible ways that documentation should be written, especially when they’re excited to be getting on with the next task. It’s also ridiculously hard to QA a completed task if there’s no detailed list of what docs should have been written.

    When I’m not intrinsically motivated to complete a task, I break it down into steps so small that each one is “obviously trivial, I can do that in five minutes”, and then there’s no reason not to do it. It’s the same thing here — “document as needed” is big, scary, open-ended, and doesn’t have an obvious starting point. “Document how to do this, place it here” is a series of small, simple, completable tasks, and there’s no mental block over where to put the docs to get in the way.

  • Consciously budget time in your project plans for docs. I prefer to make it a separate column in the project plans, but whether it’s included in your other estimates or not, it definitely needs to be included in the budget or it’ll never get done.Separate line items for documentation allows you to do your evidence-based scheduling more accurately (which is always good, as it shows you whether your doc time budgets are accurate or not) and — most importantly — says to everyone “I have explicitly set aside time to document this, so there’s no excuse not to do it”.

    On the other hand, making it explicit that you’re spending half your time writing docs gives meddlesome senior executives yet another thing to haggle over and pressure you to cut from the schedule (“What? Three weeks of your two month project is writing documentation? Are you insane? The board wants this done by last week! Get out of my office!”). Only you can decide if your corporate culture permits you to make it explicit, but if you want docs, you can’t not budget the time somewhere to make it happen.

  • Include constant documentation review and improvement in all your operational processes. For example, our monitoring system alert handling procedures mandate that every alert goes into a ticket, and the ticket doesn’t get closed until it’s been through a set of review procedures, which include checking that it’s not a recurring problem (and fixing that), adjusting whatever needs adjusting if it was a false positive to make sure it doesn’t happen again, and — the key point in this discussion — fixing any documentation that wasn’t as good as it could be in helping to solve the problem. Don’t let any opportunity to improve your documentation go to waste.
  • Hire for technical writing skills. Make it a mandatory item in your interview process that the candidate demonstrate the ability to string a few written technical sentences together in a comprehensible way. Also, if you’ve got anyone in the team already who can’t write, encourage them to improve their writing skills — going as far as paying for them to attend a creative writing course (on company time, of course), or even running something internally if you’ve got enough people who can’t write. All of this emphasis on good written communication skills will make it obvious that you value good writing, and will encourage people to obtain and maintain those skills.
  • Be the change you wish to see in the world. Demonstrate that documentation writing is for everyone, by holding yourself to the highest possible standard. Document everything you do and know meticulously, do it as you do the work, and basically follow all the good advice you’re giving to everyone else. This doesn’t mean that you write all the documentation yourself (if you’re a manager, the chances are that you don’t know enough about everything to do it properly, anyway) but the work that you do do needs to include full and complete documentation.
  • QA docs along with the rest of the deliverables. Whenever you have a QA review of work done, make sure that it explicitly includes reviewing the accompanying documentation, both for style and substance, but also that the purpose of the documentation is met. Emergency recovery procedures look very different to project planning notes.
  • Ensure that people are kept up to date with changes, by having edits (including a diff of exactly what was changed) e-mailed out to everyone. I can’t believe that there are wiki systems that don’t do this, but I certainly will never use one of those systems (again) if I can avoid it. It’s just way too useful a feature to forego.The benefits are many and varied: it keeps the presence and quality of the documentation firmly in everyone’s mind; it’s an immediate QA process; people can’t get away with shoddy edits because everything they write immediately gets seen by everyone else; and, as processes change and improve over time, everyone’s kept up to date on those changes so they’re not doing things in the old, inferior way.

Given that long list of “Do’s”, here’s a don’t: espousing the need for documentation without doing anything else. “Yes boss, we all know how important docs are, but the project plan is already unrealistic even without any writing, and every time we try to write anything you roll your eyes and tell us to get on with the more important things, and you put the kybosh on hiring that extra person to help out with the extra workload, and oh yeah, you never write anything down yourself so what the hell?”

Next time, I’ll talk about how we structured the wiki for Project Starbug.

One Comment

  • Will says:

    Hi Matt,

    Really useful article – particularly “In your project plans, explicitly describe the documentation to be written for every single step” – obvious now, but not five minutes ago!

    I’d love to read about how you structured the GitHub wiki.

    Thanks!