---
title: "How Much Should You Document? Everything? Strategies for an Agile Environment"
date: 2008-09-09
description: "$( document ).ready(function() { // Handler for .ready() called. $("
canonical_url: https://idratherbewriting.com/2008/09/09/how-much-should-you-document-strategies-for-an-agile-environment/
---
# How Much Should You Document? Everything? Strategies for an Agile Environment
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?](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/softwaretoc2.png)

Alistair explains that you can't document everything, and he quotes from Martin Fowler's ["The Almighty Thud."](http://www.martinfowler.com/distributedComputing/thud.html) 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?