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?

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

• Listen to this Boagworld podcast for details on agile methodology.

• Read this post on extreme technical writing from a tech writer’s point of view.

No, podcasting is not dead. But I’ll explain my break.

• I’ve been riding the bus/train to work for the past 9 months (I actually got rid of my old car, which I had to jumpstart each morning). I used to listen to podcasts all the time while commuting to work, but now that I can sit down on public transportation, I open my laptop and write instead. I’ve noticed that when I don’t listen to podcasts, I’m less motivated to record my own.
• In analyzing my own talents and interests, I think I’m a much better writer/blogger than podcaster. I don’t have a radio voice, nor do I have the rhythm and balance of a Leo Laporte, who can drive a seamless conversation among 5 people for an entire hour. I decided to focus my efforts on my strengths.
• When I stopped podcasting, I didn’t hear complaints from anyone. No one asked, Tom, what happened to the podcasts? Tom, when is the next podcast coming out? However, I do track all downloads using Podtrac, and on average, each month listeners download 2,000 podcasts. (2,000 downloads may seem small, but given the small population of technical communication professionals, 2,000 is a sizable chunk of users; only about 1,300 people attend the annual STC conferences.)
• Podcasting has no financial reward for me. In the past, I’ve traded advertising for software, but now that I have all the software I need or want, I need to pursue a different advertising model, which I haven’t defined yet.
• I became a bit bored with the interview format, and I wanted to switch to a more Digg or TWIT style of podcasting — a conversation about the latest news. But I haven’t put together a co-host team nor found a regular time for gathering them.

As has happened during past breaks, I miss podcasting. Podcasting has a special community feel around it — engaging with other professionals in my field, listening to voices rather than reading sentences, driving and learning at the same time. I just miss it. It feels good to listen to podcasts, especially to hear the voices of other technical communication professionals in my field.

I just listened to Alistair Christie’s latest podcast (“Being the Only Tech Writer”), which he recorded after a 9 month absence. Apparently he began a non-tech comm role at his company for a while, and just recently switched back into tech comm again. I loved hearing the conversation — a casual but focused exchange.

I still can hardly believe there aren’t more tech comm podcasters. The field is open. I suppose given my position and the popularity of my podcast, I would be a fool to simply give it up, or cease the momentum. I’m positioned right now to be an incredible source of information for podcasts in technical communication.

Last night I was thinking about my online strategy. Blogging is really just a hobby, but I’m realizing that it is going to be a lifelong hobby. I enjoy blogging, as does my wife Jane. We often blog together. (Right now it’s past midnight and Jane is upstairs writing a post she’s been telling me about all day.) When I have free time, I like sitting down to write a post.

And I like podcasting. Especially listening to podcasts while driving. One of these days I’ll solidify a financial model around my online presence, creating at least a secondary income stream based on all my online activities. Podcasting is part of that plan. But even without it, podcasting has its reward. I connect with dozens of professional colleagues all around the globe.

Today I just listened to another episode of the WordPress Podcast. Episode #44, with Charles Stricklin. It was a completely enjoyable experience, making an hour of driving time pass painlessly by. If all goes well in the next month with a house deal, I should be driving more, and listening to more podcasts.

So this is a long way of saying that I’m going to be publishing more podcasts, and I hope to be more regular in my release of podcasts. If you have suggestions for podcast topics, do let me know.