What should you include in your user documentation?

Technical authors are faced with limited time and resources, so they often are faced with the dilemma as to what to include and what to leave out of their user documentation. You may ask, if 80% read only 20% of the content, is there any value in documenting the rest?

Technical Authors are often great advocates of doing away with what doesn’t add value in documentation. However, in an article “How normal is normal?“, John Casti explains why extreme events like a killer hurricane occur far more often than we think.

So does this mean that your rare and unusual topics in documents do need to described, after all?

Casti discovered there was greater likelihood to extreme values than we’d expect from bell-shaped, normal distributions:

“Just as with the meltdown of the global financial system, the normal distribution dramatically underestimates the likelihood of unlikely events. Such events follow a different type of probability curve informally termed a “fat-tailed” distribution.”

Indeed, he states Pareto’s (80-20) principle is closely related to fat-tailed distributions:

“In a normal bookshop, there might be around 100,000 titles on the shelves of which 80 per cent don’t sell a single copy during the course of a month. Here the 80-20 Rule prevails. Now consider amazon.com, which has nearly four million titles available, or perhaps an online music site like iTunes, and ask how many of the titles they have available sell at least one copy in a month’s time. The answer is not 20 per cent or 50 per cent or even 80 per cent. It’s a staggering 98 per cent! Nearly every single title gets some action nearly every single month.”

There are also implications regarding information architecture and site navigation in Casti’s article:

“What’s needed, (Chris Anderson) he says, is for there to be a functioning way to drive demand for those niche products out near the end of tail. First you need a ‘head’, consisting of a relatively small number of hits. Then comes a tail of many niche volumes, the kind only the author, his mother and a small band of fanatics and connoisseurs could ever love. So there must be not only a huge inventory of products, but also a way to direct prospective customers from the head to the tail by means of suggestions, background profiles from past purchases and all the other things a place like amazon.com does to match readers with the books they really want.”

So does this mean that users navigate to the “niche” topics via the popular “head” topics? Do you need a “head topic” to bring the users in, with a filtering and suggested topics mechanism to direct them to niche topics, to service any customer’s wishes?

I’m not aware of any user assistance-related usability studies that have looked into this. Perhaps there is, as Casti claims, “a lot more going on out on the ‘fringe’ than we ever imagined”. As more content is published online, and more Web analytics-derived statistics becomes available to Publications Managers, then perhaps we’ll find out.



Interesting questions here. Questions about the 80-20 rule aside, when you begin to look at numbers, it’s important not to forget the qualitative side of its use-cases: while a topic might only get 1% of views, the context in which these views happen may have relatively high importance- perhaps the topic troubleshoots a workaround for a rare but catastrophic bug, or perhaps it’s something that people only turn to if they need emergency or out of hours help…


The ‘head’ pages sound very like the ‘landing pages’ Matthew Ellison has talked about, no?

The idea of which is to present links to useful (ideally “most visited”) information as soon as the user enters the online help at a particular point. Something we’re trying to figure out for our system at the moment.

Rainer Ottmueller

> Casti discovered there was greater likelihood to extreme values than we’d expect from bell-shaped, normal distributions:

BTW, he did not discover this; but it is known for a very long time. It means that the normal distribution is not an ideal, not even a realistic model. Anyhow, it is used merely for it’s simplicity to deal with it “scientifically”. You can not expect realistic forecasts, this way.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.