Helping the world explore and understand content management and technical communication
The problem is, people really don’t read the documentation. That is, they do not sit down in a comfortable chair with a cup of coffee and set out to read manuals from cover to cover. People read novels. They don’t read documentation. Continue reading ...
Often we seem to be questing for an ideal document in the belief that if we could write it, an ideal reader would emerge to read it. Wanting documentation to be better is a good thing, of course. Wanting it to be ideal may be a fatal vice. An ideal document requires an ideal reader – its status as ideal cannot be measured against any other standard. But ideal readers do not exist. In fact, as readers, the people we actually write for are generally pretty bad. Continue reading ...
We worry far too much about trying to create a logical well organized documentation set. We would do well to focus more on writing one good page. That is the best thing you can possibly do for your readers today. Continue reading ...
Every document is written for a reader, which means that every writer has a theory of the reader -- an idea of who the reader is. In technical communication, the reader is a user (of a product or service). Every technical writer, therefore, has a theory of the user. However the theory of the user manifests, it profoundly affects how the document is written. Continue reading ...
My book is currently in the final stages of revision, and I have been very fortunate to have some of the leading lights in tech comm agree to provide feedback on my drafts. So far, no two people have said the same thing about the same passage, not even once. You can't please everyone. Continue reading ...
Traditionally tech comm has tried to steer clear of marketing and all its works. Many tech writers still seem to have a strong aversion to anything that smacks of marketing, regarding it as either fluff, or outright dishonest. Here’s the problem, though. The buyer is a user too, and what works for the novice user, or for the expert user, does not always work for the buyer. Continue reading ...
As I begin my stewardship of the Users' Advocate column, I think it is important to begin by asking, where have all the users gone? Thirty years ago, tech comm had a more or less captive audience. If users wanted information on your product, they looked at the manual. They didn't have much choice. Today, when the user has a question or encounters a problem with your product, the first thing they do is to Google it. Continue reading ...
Dieter Rams, a German industrial designer from the functionalist school, followed a philosophy that will sound familiar when I paraphrase it: “form follows function” and “usability is fitness for purpose.” You know his work if you've used any Braun products released from the 1960s to the 1990s, or if you've used recent Apple products, many of which were inspired by his design principles. Let’s look at what technical communicators can learn from these principles—and when we should consider violating them. Continue reading ...
Practicalities are obstacles you can solve by choosing an appropriate strategy and then gritting your teeth and doing the necessary work. Because they aren’t psychological barriers, they’re much easier to get past because all you need to do is force yourself to follow the appropriate steps, possibly with help from friends and colleagues. You don’t always need your muse to be able to write: some aspects of writing, such as developing a timeline or plot outline, are fairly mechanical. Since you’re the only one who will see them, they don’t have to be perfect. Continue reading ...