There’s an interesting discussion thread in the ISTC’s discussion forum regarding good and bad examples of technical writing. Incoming ISTC President Alison Peck has been asked by a researcher for a radio programme if she could provide some examples of technical writing: “well done, badly done and particularly innovative or strange”. As it’s a radio programme, these examples are likely to be read out.
This is not as straightforward to answer as you might think.
Firstly, most technical communicators work under non-disclosure agreements, so the best and worst examples often aren’t for public consumption.
Secondly, a lot of poor examples are from content that has been badly translated into English. They may have been well written originally, but they might have become mangled through the process of localising the content.
Thirdly, as Alison pointed out in her original message in the online forum, reading out very basic instructions out of context is not going to be particularly riveting or easy for the listener to grasp.
Fourthly, although technical communication is about clear communication – clear sentences – the role of technical communication is mostly about addressing the question, can the user do the task?
Minimalism, which most technical communicators use, focuses on:
- Adopting an action-oriented approach (to minimise the amount of reading)
- Starting immediately on meaningful tasks
- Supporting users in recognising errors and recovering from them
That requires more than clear and simple sentences; it requires information design as well. This means any examples ideally should show how well or badly they enable the user to complete the task. That requires an understanding of the task itself, and this makes it difficult to do this in a few seconds on the radio.
Ellis, you might be onto something.
A bad example of technical writing is much like a typical radio program. To accommodate a wide audience, a radio show must include a general introduction to the topic that takes way too long. Any listener already familiar with the topic is impatiently waiting for the part that is relevant to them. But that part doesn’t come until the end of the show, if at all.
There’s endless drivel about “interesting” background trivia rather than solving the listener’s task at hand. You can’t fast forward, you can’t search, there’s no navigation whatsoever; this is radio.
Let’s say you are lucky and the host takes your phone call. You ask your question. The experts on the show skirt the question and fail to understand your issue. You cannot comment since you only get one phone call. Once the program is aired and recorded it can no longer be changed. It’s an unmutable monolith.
I’m sure we have all read technical documentation like this.