There are no Prerequisites

There are few worse ideas in technical communication than the idea that procedures have prerequisites. There are no prerequisites. There are only steps.

To illustrate: Last weekend I paid a visit to some family members who were camping at a nearby campground. They were struggling to inflate the new air mattress they had bought. The mattress had an integrated foot pump, but no matter how they pumped, the mattress refused to fill with air.

Several of us took our turns trying. Each of us read the instructions and did what they said to do, all to no effect. The decision was eventually made to return the mattress to the store, and discussion turned to whether to go home or sleep on the ground. read more

Tech Writers Must Learn to Stage Content Better

Some technical writers are proud of the utilitarian nature of their content. This isn’t marketing, they will say, with no attempt to veil their contempt for anything that might please or persuade. The customer has already bought the product, they will explain, so there is nothing left to sell.

This is wrong on a number of counts.

Documentation has to sell

There is a lot left to sell after the user makes an initial purchase. There are more copies to sell across the user’s organization. There is the next version to sell. There are other products your company wants to sell. There are the people that each current customer influences that your company want’s to sell to. But even more basic than this, your content has to be sold to the user. True, you are not asking the user for cash; just for time and trust. But time and trust are currency, and if we cannot command the reader’s time and trust, how can we expect to command our salaries? read more

Docs that are Part of Larger Systems

It is easy to think of documentation as simply the reader’s companion, which they use when they need help with a product or service. But a lot of documentation is more than this, it is part of an industrial or institutional system. Designing and writing documentation to be part of such a system can be quite different from writing stand-alone documentation.

Software documentation vs. everything else

There often seems to be a divide in the technical writing community between those writing software documentation and everyone else. Everyone else includes fields such as manufacturing, medical, and insurance. People working in the “everyone else” camp often complain that much of what is written about technical communications, and many of its tools and so called “best practices” are only looking at software documentation and ignores the needs and practices of “everyone else”. read more

The Reader’s Path Cannot be Made Straight

The straight path. It is an idea with immense psychological appeal to us. Every valley, Isaiah promises, shall be exalted, and every mountain and hill laid low (Isaiah 40:4). As communicators, we naturally want to lay out a straight path for our readers. But the truth is, we lack the power to make the crooked straight and the rough places plain.

The crooked path and the paradox of sensemaking

A crooked path through a forest.

The reader walks a crooked path through a forest of information.
Simon Carey [CC-BY-SA-2.0 (], via Wikimedia Commons

In his landmark book, The Nurnberg Funnel, John Carroll described what he called the paradox of sensemaking, which can be roughly summed up as saying that learners cannot make sense of the learning materials because they don’t correspond to their current mental model, which can only really be changed by experience. No documentation can ever work perfectly, therefore, because it can only make perfect sense to someone who already understands what it is saying. read more

Safari Flow and the EPPO-fication of Books

Summary: Safari Flow represents a move to Every Page is Page One navigation for books, but its success is limited when the content is not written in Every Page is Page One style.

At Tom Johnson’s suggestion, I have recently subscribed to Safari Flow. Safari Flow is a new take on the Safari Books Online concept which allows you to rent online access to a large library of technical books. What makes Safari Flow different? Essentially, it takes an Every Page is Page One approach to the navigation of the content it provides. read more

Content is a Utility

Summary: When content is a utility the job of the tech writer is to ensure reliability of supply.

In my earlier post, Content as Furniture, I suggested that while content used to be furniture — something to be acquired selectively and displayed as a prized possession (and a mark of status) — it is rapidly becoming a utility — something we simply expect to be there when we need it, like water or electricity.

The notion that content is becoming a utility has some pretty important consequences that I think are worth discussing. read more

Design for Wayfinding

Much of the time we spend with technical documentation is concerned with wayfinding. That is, it is not about performing the actual operation, but about finding which operation to perform, and finding the piece of content that describes the operation in a form that we can understand.

Note that there are two distinct components to this description of wayfinding. It is tempting to think of wayfinding purely in terms of finding the right piece of content. But simple content wayfinding really applies only in cases where the user it thumbing through a well known and well used reference work. That is, in cases where we know exactly what we are looking for, and merely have to locate an individual data point. read more

Content as Furniture

Summary: Content is no longer furniture; it is a utility. We have to learn to treat it as such.

I am in the last throes of our move from Ottawa to Kitchener-Waterloo, Ontario, which involves moving a lot of content. Boxes and boxes of great heavy lumps of paper and ink content. Great gaping room-swallowing wooden content storage units. Think those old hard drives in the computer museum (or your basement) were costly and low-capacity? Let me show you a book case. More to the point, help me move it. read more