Want Respect? Get out of Publishing

I recently wrote the following in a comment on Tom Johnson’s blog post What Tools Do Technical Writers Use:

That writers are still expected to do their own publishing strikes me as one of the tragedies of the profession, and a major part of why tech pubs does not get the respect it thinks it deserves in organizations. It is a big part of the reason that so many people still dismiss what tech pubs does as “making it pretty”.

It was not the most deeply considered statement I have ever written, and when I read it over after having posted it, I rather wondered at the sentiment it expressed. Why exactly should engaging in publishing lose you respect? It’s not as if people universally lack respect for publishing. It’s not as if publishing is something akin to pyromania or politics, rightly despised by all. Yes, there is the “making it pretty” thing, but why exactly should the ability to make content pretty lose you respect? People are not generally opposed to pretty. They like pretty. They pay a lot of money for pretty. read more

Book Review: Back of the Napkin

I tend to have a reputation for being anti-graphics in technical communication. I’m not. I think graphics can be very powerful, if used appropriately. But I also think that graphics are very often used badly, and that a bad graphic is even worse than bad text.

The problem, it seems to me, is that graphics have no inherent grammar. Unless a paragraph is truly butchered, you can usually puzzle out its meaning, because a language has only one grammar, one way of putting words together to make meaning. But what is the consistent and agreed meaning of a thick arrow versus a thin, a circle next to a triangle, or a broken line versus a solid one? When a graphic fails, therefore, it fails utterly. read more

Tech Comm’s Place in the Choir

All God’s creatures got a place in the choir
Some sing low and some sing higher
Bill Staines

Birds on a wire

A place in the choir

Traditionally, technical manuals have been written as if they were the only source of information on a product. Of course, the manual was never really the only source. There have always been neighbors, friends, colleagues, retailers, user’s groups, and professional associations to learn from as well.  But access to these other sources of information was not universal, and those groups themselves had to learn from somewhere — information had to propagate through the network before it became available to the ordinary user, and the propagation was usually quite slow. It was reasonable, therefore, for users to look on the documentation as their principle source of information, and it was reasonable and necessary for the documentation to be written as if it were the sole source of information on a product. Not any more. read more

Why documentation analytics may mislead

I was rereading some material in the long-running do-people-read-the-manual debate (such as Tom Johnson’s If No One Reads the Manual, That’s Okay), and it struck me that there is an assumption that people on both sides of this debate are making which deserves some scrutiny. We all assume that technical documentation operates at first hand. That is, we assume that when a user wants help, they get that help directly by reading the manual or the help system or by watching a video, etc. I don’t think that assumption is correct. In fact, I’m convinced that it is naively and dangerously wrong, and that measurements and decisions based on this assumptions may be fundamentally flawed and harmful to a company and its customers. read more

Technical Communication in Children’s Literature

I recently came across a reference to technical communication in a children’s book. I’m wondering how many other such references they might be. (The topic seems apt given Tom Johnson’s recent questions about the place of technical writing in the high school curriculum.)

I was delighted when I found out recently that Joan Aiken‘s Armitage family stories has been collected and published together, and that the collection was available for the Kindle. The best known of these stories is The Serial Garden, which is the name given to the new collection, but there are a number of others that I had never read before, including one called Miss Hooting’s Legacy, in which the Armitages are bequeathed a pair of “mechanical helots” (in other words, robots) in the will of deceased old fairy lady (in other words, a witch). read more

Cars, trains, and puzzles: three approaches to topics

Everyone is wild about topics, and rightly so. Topic-based writing offers many benefits for both readers and writers. But not all topics are created equal, and how you serve your readers, and how efficient you make your writers, can depend on which approach to topic-based writing you choose.  We can usefully distinguish three basic approaches, which I will call cars, trains, and puzzles.