The Long Tail and Why Docs are Frustrating

It is often a matter of some perplexity to technical writers that more and more people seem to prefer searching the Web rather than looking for information in the documentation. It is perplexing because information found through a Web search is of variable quality, sometimes hard to navigate, lacking in authority, and has to be picked out of a big pile of fluff.

Why would people prefer to search the sprawling mess that is the Web when they could look in the neat, authoritative, well organized documentation set? Shouldn’t they, at least, look in the docs first before turning to the Web? read more

Are Docs a Responsibility or a Business Asset?

Do we write documentation to fulfill a responsibility, or to create a business asset? Are we striving to meet a set of requirements pronounced by either convention or regulation, or are we striving to increase corporate revenues and contribute to shareholder value?

The question is provoked by an interesting discussion with Jonatan Lundin in the comments on Tom Johnson’s post Using Tags to Increase Findability. (The discussion has virtually nothing to do with using tags to increase findability — sorry Tom!) Jonatan’s position (if I have understood him correctly) is that tasks can be divided into product-centric  and organization-centric, and that documentation should stick to covering product-centric tasks and not touch organization-centric tasks. My position is that the user’s task is to use the product’s features to meet the organization’s goals and that if we are going to produce task-oriented documentation, therefore, we cannot ignore the user’s business domain. read more

Tech Comm’s Place in the Choir

All God’s creatures got a place in the choir
Some sing low and some sing higher
Bill Staines

Birds on a wire

A place in the choir

Traditionally, technical manuals have been written as if they were the only source of information on a product. Of course, the manual was never really the only source. There have always been neighbors, friends, colleagues, retailers, user’s groups, and professional associations to learn from as well.  But access to these other sources of information was not universal, and those groups themselves had to learn from somewhere — information had to propagate through the network before it became available to the ordinary user, and the propagation was usually quite slow. It was reasonable, therefore, for users to look on the documentation as their principle source of information, and it was reasonable and necessary for the documentation to be written as if it were the sole source of information on a product. Not any more. read more

Crossing the chasm with documentation

I was reflecting today on whether companies are making the best strategic use of their documentation departments. Of course, we doc folk believe that no self respecting corporation should ever let any product go out the door without full, brilliant, richly illustrated documentation — preferable printed on acid free archival quality paper and bound in rich leather embossed with gold lettering. In fact, of course, that virtually never happens, and yet our companies still manage to eek out a return for their shareholders. read more