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

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

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

Links are Not About the Relationship Between Texts

One of the most important distinctions we need to make when writing for the Web is the difference between how texts are related and how subjects are related. If that sentence made you say “Huh?”, let me explain.

In the book world, the principal reason for one book to refer to another book or article was for purposes of citation. A citation says, for support for this claim, see this work. The citation is used either to prove an assertion about another text, or to support an assertion about a subject with reference to an authoritative text. Any old text on the subject won’t do. It is the authority of the specific cited text that is being invoked. read more

On the Web, Context is Vital

Supply subject area context; avoid institutional context.

In a recent blog post, On the Web, context kills, speed saves, Gerry McGovern states:

A key difference between web writing and writing for print is that on the Web you need to avoid context and instead focus on instructional, how-to, task-based content.

Since one of my seven principles of Every Page is Page One is that an EPPO topic establishes its context, this quote made me think that either Gerry McGovern had gone bonkers or he was using the word context in a very different way than I use it. Turns out that it is the latter. (Sorry if you were hoping for fight here.) I actually agree with almost everything that McGovern says (I’ll get to the part I don’t agree with a little later). In fact, I have said many of the same things before, but in a different way. read more

How to be Edited

The key to survive being edited is not to look at the edits.

There is a lot of advice available on how to edit other people’s work, and how to edit your own, but not much on how to be edited by someone else. Here’s some thoughts on how to make it a relatively less agonizing process. The key is, don’t look at the edits, look at the result.

The agony of being edited

I’m nearing the end of having my book edited. I submitted the “final” manuscript a couple of weeks back, and since then my editor and publisher, Richard Hamilton of XML Press, has been copyediting and feeding the result back to me a chapter at a time. Since one of Richard’s stated aims in the copyedit was to trim back the manuscript significantly, I was prepared to this to be a painful process. read more

Readers Express their Purpose in Terms of Tools and their Features

One of the samples of an EPPO topic that I included in my book was a topic from the WordPress Codex on the subject of Using Themes. One of the key properties of an EPPO topic is that it serves a specific and limited purpose. I identified the purpose of this topic as enabling the reader to use themes on their WordPress site.

One of the reviewers objected that the user’s real purpose was not to use themes, but to style their site. I can understand where the criticism comes from. Those of us who favor task orientation in technical communications are quite sensitive to anything that smells of its opposite: feature orientation. We don’t want people to be writing topics on the File Menu, for instance. We want them to focus on things that the reader is trying to do. read more

The Big Step Back and the Small Step Back

My Book is currently in the technical review stage — meaning that people who I and the publisher respect have been asked to read and comment on the full draft. It is a humbling, daunting, and also energizing experience, and I am deeply grateful to the reviewers for their time, energy, and expertise.

One of the reviewers asked why the book is not itself written as a collection of EPPO topics. It’s a very fair question, and one I have attempted to address before. But I think there is more to be said on the subject, or, at least, another way of saying the same thing — which is often just as valuable. I think of it as the difference between a big step back and a small step back. read more