The incomplete bridge

In the Top Gear Patagonia Special, the presenters come upon an incomplete bridge and have to construct a ramp to get their cars across. This is a great metaphor for technical communication, and, indeed, communication of all kinds: the incomplete bridge.

Technical communication is often described as a bridge between the expert and the user. But that bridge is always incomplete. The user always has to build the final span that connects the bridge to the bit of ground they are standing on.

This is true for several reasons, the most basic of which is that you have to contextualize any information you receive to your own project in order to act on it confidently and successfully. If the document tells you to push the red button, it is still your job to determine if you are looking at the right device and the right red button, and if your purpose will truly be served by pressing the red button at this time. The document can never entirely ensure that you do not press the wrong button on the wrong device or at the wrong time for the wrong purpose. Only the individual reader can determine those things, and thus only the reader can build the final span of the bridge. read more

Content is a Republic

I’d thought the Content is King debate was over, but I saw it rearing its jester’s head once again recently. Argh!

“Content is King” is a phrase that seems to have come out of content marketing to express the simple idea that content is now the most important form of marketing. Which is actually a rather weird and restricted meaning of the word content, since it was meant to contrast with traditional advertising which is, after all, content.

What I think those who coined the term were really trying to say is that in marketing content that informs now performs better than content that attempts to persuade. This is a direct result of content being easier to get on the Web, which means that readers can get the information they want while avoiding any overt attempt to persuade them. read more

Good Enough Solutions Fast and Easy

It is easy to set an ideal for technical communication that it should deliver the best solution — the ideal solution — to every problem. Many critiques of Web search as a tool for finding technical solutions focus on the many less than perfect solutions that any search query returns.

How is the user to find the ideal solutions in the midst of so much dreck? Wouldn’t they clearly be better off confining their search to the official product manual?

No, and here’s why:

The manual does not always have the best solution

First, it would be a stretch — an outrageous stretch — to suggest that a stand-alone manual always contains the ideal solutions to every question. read more

Successful Patterns are the Best Guide to Information Design

I am very grateful to Jonatan Lundin for a lengthy conversation on the subject of topic patterns because it helped me to crystalize something important about the basis for the principles of EPPO information design and how they are derived.

Approaches based on psychology

Traditionally, theories of information design have been psychologically based. Researchers (usually academics) attempted to form a psychological theory about how we learn and then suggested information design approaches based on those theories. The success of such efforts has been mixed. read more

Subject First; Context Afterward

In communication, they say, context is everything. Actually, “everything” consists of context and subject. Useful information is subject in context. The question is, which comes first: context or subject?

In the book era, the content search pattern was: context first, subject afterwards. That is, suppose you deliver three different products and have released three different versions of the product. Assuming only a single manual per product/version that meant you had 9 manuals, each with a page on feature X. read more

The Death of Hierarchy

Hierarchy as a form of content organization is dying. A major milestone — I want to say tombstone — in its demise is the shutdown of the Yahoo directory, which will occur at the end of the year according to an article in Ars Technica, Yahoo killing off Yahoo after 20 years of hierarchical organization. (Actually it seems to be offline already.)

As the article observes, a hierarchical directory made some sense when Yahoo was created:

In the early days of the Web, these categorized, human-curated Web listings were all the rage. Search engines existed, but rapidly became notorious for their poor result quality. On a Web that was substantially smaller than the one we enjoy today, directories were a useful alternative way of finding sites of interest. 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 (http://creativecommons.org/licenses/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

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

Passive vs. imperative linking

Summary: Writers worry about whether links will distract users. To discuss this concern, we need to begin by distinguishing between imperative links that command the reader to click and passive links that merely make finding ancillary material easier.

Tom Johnson wrote a post recently in which he raised an important question about linking, and referred to an earlier article of mine on the subject. When you refer to another document in a post or article, should you link to it immediately? Tom wrote: read more

Short: good policy, bad metric

We seem to agonize endlessly over how long content should be. Metrics are regularly proposed for the perfect length of a blog post or content marketing piece, and the move towards topic-based writing has tech writers worrying about similar issues. Keeping content short is certainly good policy. No one wants to read more than they have to to accomplish a given goal. So it makes sense to use content length as a metric for content quality, right? Not so much. Short is a great policy, but a lousy metric. Here’s why:   read more