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

Structured Writing and Free Trade

In my last post, I promised I would reveal the unifying idea that I developed for my new book on Structured Writing. This is the post. So what does it have to do with free trade? Mostly it is that I see the same pattern in discussions of free trade that I do in many discussion of structured writing: a failure to focus on the big picture.

Free trade has been pretty much a given for the last several decades with nations and trading blocks negotiating ever freer trade. But of late the virtues of free trade have been called into questions by the Trump/Sanders wing of American politics, which has those of us in Canada, for whom America is our largest trading partner, a little anxious. read more

Designing for Feedback

We were discussing the biggest challenges in Tech Comm at the last STC Toronto brunch and we all seemed to agree that the difficulty getting feedback on the effectiveness of the content we create is the biggest challenge. The things that really matter in technical communication is whether users can achieve their goals after finding and reading the docs, and whether that makes a difference in whether they buy from you again or speak well of you to their friends and colleagues. These things are incredibly difficult to measure. You are just not there to see them happen, and it is very difficult to separate their effects from the effects of the work that designers, developers, sales people, trainers, field engineers, and support staff do. read more

Why does XML suck?

XML sucks. Don’t get me wrong. All kinds of really valuable and important systems use XML to perform vital functions. But performing a vital function does not keep something from sucking. Lots of people think Windows sucks, but it performs a vital function, and lots of people use it because of that. In fact, performing a vital function is what keeps sucky things around. If they perform a vital function, they are hard to get rid of, despite the fact that they suck.

Not that that prevents people from trying to work around them. read more

Let’s Replace “Content” with “Story”

We used to be in the writing business. Then we were in the communication business. Now we are in the content business. It’s probably getting time to change the monika again. I have a candidate: “story.”

There have always been two schools of thought about the word “content”. Some love it. Some hate it.

I hate it. It is an ugly generic word chosen specifically not to mean anything specific. We can’t say “writing” because sometimes we use pictures. Etc. Etc. It is the sort of word you use when you don’t care what is in the container. (Many years ago I asked a Documentum rep what Documentum meant by content, to which he replied, “anything you can store in Documentum.”) read more

Is There a Reproducible Method for Explanation?

In a recent LinkedIn discussion on “Most important competencies for technical writers“, I commented that the most important skill for technical writers was explanation, and that the ability to write and the ability to explain are not the same thing, and that the ability to explain is significantly less common that the ability to write well enough.

This scarcity of natural ability to explain well, I argued, is why we need to pay attention to tools and structure, because we need to find ways to help people who do not have a natural gift for explanation to explain things at least reasonably well. Tacitly, this argument suggests that there is a reproducible method for explaining things. read more

7 Keys to the Discipline of Linking

Following my recent STC Webinar on Every Page is Page One, an attendee wrote to ask about the discipline of linking. Unfortunately, that email mysteriously vanished from my inbox before I could answer personally, so, whoever asked, I hope you see the answer here.

Linking is important to Every Page is Page One and to a bottom-up information architecture. When readers can enter your content at any individual page, links are what orient them in the larger content set and what keep them in your content rather than sending them back to their search engine. read more