Thursday, November 20, 2008

Is there a case for "Just Enough" Documentation?

A couple of what at first glance appear to be disparate unconnected posts picked up by my Twitter feed over the last few days got me thinking about just what we should include when we produce product documentation.

On her Twitter feed consultant Sarah O’Keefe posted the following quick observation: "Inbox Zero once again. Today's lesson: When you ignore stuff, much of it becomes irrelevant.” This is a productivity, time management technique that I have used for years. One of the first things I was taught at management college was that never keep anything on the “to-do” list longer than 30 days. If you haven’t got around to it in 30 days and no-one’s complained it probably wasn’t that important. Delete it, and if it is important someone will remind you. Like Sarah I also apply a similar philosophy (but not time scale) to the contents of my Inbox.

Then today, Alyssa Fox from NetIQ posted a quick note on her Twitter feed that “SE just found a bug in our doc that's been in there 5+ years. Obviously no one ever reads that section,” to which I responded “If no-one's read that doc in 5 years - is it really necessary to have it there at all? Why write and maintain something no-one uses?”

Over lunch I began to realize that the two thoughts had a definite connection. Traditionally we tend to document every feature and function of a product. We expend many hours describing how something works. Yet how much of what we produce is ever read or used?

Most users are only interested in learning how to set something up and start using it in the shortest possible time. Secondly they want to get answers to very basic “how do I” type questions. With this in mind I’ve recently been conducting an ad-hoc, and very unscientific, straw poll about which documents (print, on-line help etc.) that people are most likely to use. The result is very clear that the thicker and more voluminous the documentation appears, the less likely people are to use it.

So going back to the “ignore it and it becomes irrelevant” thought. If sections of documentation are never read, accessed or used, are they irrelevant? While the engineers and designers may not think so, it seems clear that the users do.

Is there a case for “Just Enough” documentation.

At we recently went through a process of rewriting our complete documentation set. At least that was the original goal. Yet when we compared the old documentation set against the project time frame we realized that we would have to make a decision about what was necessary and what was just “nice to have.” The project was lead by one of our MVP users who could give us the user perspective on what was needed and what could be left out.

But how will we know if we’ve made the right choices?

We posted the new documentation set online as a wiki. We have enabled comments so users can directly tell us if there’s something we missed. If we need to, we can create a new piece of documentation and publish it quickly. But perhaps best of all we can now track which document pages are visited and more importantly which aren’t.

It may take a few iterations but we will be able to fine tune the documentation to provide just the information that our users need and use; allowing us to focus effort away from maintaining “irrelevant” dead pages to making sure that he have “just enough” documentation to make our users successful.

[This entry is cross-posted to my blog]


Alyssa said...

I like this approach - Doing the "absolutely necessary" work, and giving users an easy and quick way to tell you what you might have missed. This was a lightbulb for me in why it's good to have the doc in a Wiki format. Definitely something I hadn't thought of before. Thanks for the thoughts!

Paulm said...

It's hard to identify all the top priority product areas and use cases in advance. The 80/20 rule is a good rule of thumb, but we often "guess" wrong about some use cases. The "just in time" documentation model works well in this aspect, where we can extend the Wiki in areas where users need it.