Trust is Essential to Creating Great Docs

My good friend Pamela Clark asks me to comment on

what product development organizations, processes, and structures best support great user-oriented documentation

I’ve commented over on Tom Johnson’s blog that tech pubs organizations tend to make a slow migration through the corporate landscape, and that I believe that the best home for pubs is in the development organization. But I also believe that tech pubs success is all about relationships, and there is more to that than simply the reporting relationship. In the end, if you want to create the conditions to do great work in tech pubs, you have to be valued. read more

Technical Communication is Not a Commodity

The latest attempt by the STC to promote a certification program for technical communications prompts the thought that technical communication is not a commodity.

What does it mean to say that a profession is, or is not, a commodity? A commodity is any good which will provide the same quality and performance no matter which supplier you buy it from. Gasoline is a commodity. Sugar is a commodity. No matter which brand you buy, your car will run just as well and your tea will taste just as sweet.

A profession is a commodity if you will receive substantially the same service no matter which member of the profession you use. Accounting is a commodity. Your books should be substantially the same no matter which accountant prepares them. Technical writing is not like that. Ask two technical writers to write something on the same topic, and the results are apt to be substantially different. read more

The Best Place to Find a Needle is a Haystack

HaystacksConventional wisdom tells us that the best place for a needle is in a needle case, and the best place for hay is in a haystack. If you want to find something, or want other people to find it, you should put it in the right place. As we were all taught: a place for everything, and everything in its place.

That was true when we lived in the physical world. But we don’t live in the physical world anymore. We live on the Internet, and the Internet is topsy turvey world in which the best place to find a needle is actually a haystack. read more

The Purpose of All Communication is to Change Behavior

One of the quickest ways I have found to help someone who is struggling to formulate a message is to remind them that the purpose of all communication is to change behavior. If you put the message out into the world, and no one’s behavior changes as a result, then your message has clearly failed. Thinking about your message as a means of changing someone’s behavior does wonders to clarify the task. You really only need to answer three questions:

  • Whose behavior am I trying to change?
  • How do I want them to behave?
  • What can I say to them that will motivate them to behave this way?

If you can’t answer the first two questions, you are not ready to begin. If you can answer the third, you know exactly what you have to do to succeed. I have found this simple mantra to be a very powerful tool for focusing people on how to create a successful message. read more

Characteristics of EPPO Topics: Stay on One Level

One of the less obvious but more important characteristics of an Every Page is Page One topic is that it stays on one level. As with the other characteristics I have discussed in this series, being standalone, having a specific limited purpose, and establishing its context, staying on one level is not an ideal, but a common feature of millions of page-one topics on the web. What makes this characteristic worth pointing out is that it is something a topic does not share with books.

Approximation, Correction, and Tech Comm

Charge of the Light Brigade

Charge of the Light Brigade

At the Battle of Balaclava, an order reached a brigade of light cavalry to take the Russian guns. The general who sent the order was referring to a small artillery position that had been abandoned. But the commander of the light brigade could not see those guns. He could only see the main Russian battery at the end of the valley. He charged, and the light brigade was cut to pieces. The Charge of the Light Brigade can tell us something pretty interesting about the development of technical communication today. read more