Search results

How Much Should You Document? Everything? Strategies for an Agile Environment

by Tom Johnson on Sep 9, 2008
categories: technical-writing

In a recent IT Author podcast ("Documentation and Agile Development"), Alistair Christie and Graham Campbell talk about agile development and its impact on documentation. One consequence of working in an agile environment, they say, is the need to prioritize your documentation, to deliver instructions for only the most important or confusing features.

Presumably, some agile environments move so fast, you have to triage what you document because there's no time to document everything.

How much should you document? Everything?
How much should you document? Everything?

Alistair explains that you can't document everything, and he quotes from Martin Fowler's "The Almighty Thud." Fowler, however, takes the argument one step further, arguing that you shouldn't document everything. Fowler writes,

If you document everything, you are giving everything an equal weight. Do that for a complex system, and you are buried in detail. In any system there are some aspects that are more important than the others, key aspects of the system that once understood, will help someone to learn more. The art in documentation is to find how to document these aspects as clearly as possible. In this you emphasize these areas, and leave the details for the code.

If you document everything, you end up giving everything equal importance and losing focus on the key tasks and concepts users need to learn. You need a focal point, a selection of core tasks that receive prominence and make everything else intuitive.

Fowler continues, citing his own approach to the article he wrote as an example:

As I started to write this article I was overwhelmed by the things I could talk about. Lots of anecdotes and tips came to mind. But I know that to get you to read and remember this article I could only talk about a few of them. I had to select the key things that I had to mention. Communication is all about that. The key to good communication is to highlight the important things to say. Saying everything is not communication. That just passes the selection of the important things onto your readers, and discourages them with a heavy document. That selection of information is one of the most important parts of communication, and it is the responsibility of every designer.

I agree that selection is key to crafting any article. Were his article 20 pages, I wouldn't have read it so eagerly. Instead, because it's 2 pages, I did read it.

Alistair says that when you give someone a huge manual (one that makes a thud when you set it down), it makes the user's heart sink. "They don't think, Oh, that's great. No, they think oh, This looks grim."

Bloating the table of contents with dozens of non-essential topics reduces the focus on what customers need to be concerned about. Each additional word you add dilutes the importance of the other words. "The more you document, the less people read," Alistair says.

We all know that if you give someone War and Peace, they'll probably never read it. But give them a short story and they read it the same afternoon.

No one disagrees with brevity. Almost all users want concision. However, writing an article is different from writing a help system. In a help system, I do think almost all the features should be documented -- somewhere.

If you limit the help topics to just the core topics, what happens when the power users search for an advanced question and find nothing? What happens when Joe user wants to know how X widget functions? Is our response simply, "Sorry, we didn't think that feature was important enough to document"?

Fortunately, this whole dichotomy between (a) documenting everything and overwhelming the reader and (b) selecting what to document and risking absent information is an Either-Or fallacy. It is possible to both document everything and give the user a brief guide. Simply, document everything in the online help. Then create a quick reference guide to give to the user.

Am I missing something?

To avoid the disheartened look on a user's face as the two inch manual makes a thud on his or her desk, reduce your printed manual to a much smaller subset of the online help, rather than duplicating it. Remove all the low-priority topics. Let the reader know that full documentation is in the online help.

Since users don't typically read manuals anyway, they'll welcome this approach. No one has ever said to me, Tom, this guide feels a little thin. Couldn't you add more to it?

Fowler's advice to avoid documenting everything may reflect what he was documenting as well as his time. Fowler was documenting code, which has layers upon layers of depth. But he didn't say to leave out documentation, just to "leave the details for the code." You can add little notes here and there in the code using slashes.

Also, Fowler wrote his article back in 1997 -- more than 10 years ago. At that time, I'm not sure he had all the single-sourcing capability we currently have. Perhaps producing subsets of documentation (or multiple manuals for different roles) was too difficult.

I'd be curious to hear your approach. Are you over-documenting? What's your approach to reducing the "thud" while still delivering complete documentation?

Additional Resources

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.