The Problem with Documentation

I’ve been asking developers I know whether they think their current project is properly documented. Not one of them has said that they’re happy with the documentation they have and most have talked about the need to write more. I suspect the problem is not one of volume, but of accessibility.

I’ve realised that over my career to date I’ve spent a significant amount of time documenting how systems work. Unfortunately, too much of this has been done in a transient fashion - in a face to face meeting or by email - with the outcome that the information is largely lost with the passage of time. This doesn’t serve the project well, and it doesn’t make the best use of my time, especially when I end up conveying the same information multiple times.

In this post I want to talk about five lessons I’ve learned so far (I’m still learning!) about the nature of documentation.

Word Processors are for telling Stories

This might surprise you, but I don’t think the solution is to write more documentation in traditional document form. No matter whether you use Microsoft Word, Lotus Word Pro, Apple Pages or another word processor, writing more documentation in larger documents is not going to work.

Word Processors are tools for writers. Word processors are sovereign applications, designed to help you tell a story to take the reader on a journey. This might be a literal journey, like Frodo’s journey through Tolkien’s The Lord of the Rings; the story of one person’s date with destiny, like Paul’s journey in Frank Herbert’s Dune; or learning about an interesting topic, such as Tim Harford’s introduction to economics in The Undercover Economist.

I’m a software developer, not a writer. I surround myself with the tools needed for writing software, not the tools for writing prose. I live in Visual Studio and PowerShell, not in Word. When I write documentation I’m not trying to tell a story or take anyone on a journey, I’m trying to convey information.

Documents are Linear

Readers start at the beginning of the story and you take them through the journey step by step.

Even if you use flashbacks or change viewpoints, the story itself is told in a linear fashion and because of this they take a significant investment of time to read and understand.

In most cases when people need to consult the documentation for a piece of software, they aren’t interested in a story or a journey - they have a specific need that needs to be satisfied. Perhaps the system has failed and they need to diagnose and rectify the problem quickly; perhaps they are going to be implementing a new feature and they need understand how the new code will affect the existing system; or perhaps they have a bug to fix and need to work out where to start the investigation.

Documents get Stale

One of the real problems with the documentation that does exist is that it becomes stale.

Having thorough documentation that tells you all about the system as it stood 2 years ago provides little value simply because the content is partially stale. Some of the details will still be accurate, some will be completely irrelevant and some will be actively misleading.

There’s an invisible threshold in time, past which people will start assuming the documentation is stale in the belief that the information is no longer relevant. It might be that just a small fraction of the information is wrong, but all of it gets ignored.

Having a regular review process to check the documentation and to bring it up to date can help, but that’s a large job that never seems to occur at a good time.

Email is transient

Despite the overwhelming volume, I’ve observed the relevance of email falls off extremely quickly as time passes.

The mail app on my phone is configured to show me two weeks worth of email. The one on my laptop is configured to show me a month. Outlook, at work, shows me only 120 days of messages.

If I need an older message, I can reach out and find it - the messages aren’t automagically deleted. For personal messages, I can go to www.outlook.com; at work, we have an archive tool. But, I do this so infrequently that I have to discover how to do it anew each time.

My experience isn’t unique - in fact, I think it’s pretty typical. Email has greatest value and utility in the days after it is written. The value of a message goes down very quickly and by the time its a few weeks old, most messages are easily discarded.

I used to spent hours writing up long emails to document implementation decisions and business rules. This effort was wasted, because those emails are either long gone, or they are buried deep in an enterprise grade mail archiving tool where they would take an effort to locate.

Email isn’t read

Like many people, I receive a lot of email messages every day - it often feels like a virtual tsunami of information, threatening to overwhelm.

Many people handle this flood of information by being choosy about what they read or by limiting how much of a message they read. Some will skim a message, only reading it in depth if it seems immediately relevant or important. Some only read the first paragraph of every message, some only the first line - and a few just read subject lines.

It is therefore vital to put the critical information from any email message in the subject line if you can, or in a short first paragraph if you can’t. There’s a good chance that information buried deeper in the message will be skipped completely.

Those long emails I mentioned above are a good example. Many of the follow-up questions that resulted were asking for details already covered by the original message; it was just that the recipients hadn’t bothered to read past the first or second paragraph and instead took the shortcut of another email.

Where to from here?

While a list of five things that don’t work might be a bit depressing, that’s not where the story stops.

I have some solid ideas on what we can do better as an industry, things I now know that I wish I had known a decade ago. I’ll go over those ideas in a future post - but first I’d like to hear your stories. Sound off in the comments below.