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.
Peter J. Bogaards posted a link on Twitter yesterday to an article and a press release on how IBM is adopting a design-led approach to software design.
“IBM Design Thinking is a broad, ambitious new approach to re-imagining how we design our products and solutions … Quite simply, our goal — on a scale unmatched in the industry — is to modernize enterprise software for today’s user who demands great design everywhere, at home and at work.” (Phil Gilbert, general manager, IBM Design)
I understand the IBM Design Thinking approach will affect everything it does: product development, processes, innovation, and, interestingly, the technical documentation/user assistance associated with products. Both design and traditional technical communication share the same goals – to deliver something that is very usable, robust and aesthetically pleasing – so it makes sense to have the two teams aligned closely.
Past clients include technical communicators from Citrix, GE, IBM UK, Lloyds Banking Group, Sage plc, Schlumberger and Visa International. One delegate commented:
“The way in which customers consume our content is changing, as are the different expectations customers have regarding user assistance and support. Your course provided further insight and ideas regarding how to review and adapt to ensure content is relevant and appealing to our customers.”
This course is ideal for Technical Authors and those developing assistance for users of software.
Mark the Roofer came round to replace a broken tile on our roof late last week, and he told us that the Velux windows we’d had installed were fitted incorrectly. Apparently, up until two years ago, Velux windows needed to be fitted to the rafters, but now they should be installed onto a batten.
The consequence of fitting the newer style windows using the old method is they aren’t set high enough on the roof. The result is rainwater doesn’t drain freely, and is only held back by the surrounding felt. As the felt degrades over time (he said it’s usually two to three years), water starts to drip through into the room below.
The Velux installation guides and videos are actually very clear and well written, so it seems the reason why some builders seem to be installing the windows incorrectly is because they haven’t read the instructions in the last two years.
This roofer has read them, and makes a habit of checking any Velux windows he sees on the roofs he’s working on. It means he is able follow up many of his small £20 tile replacement jobs with larger £400 Velux re-installation projects. Sometimes, reading the manual pays.
Google Glass, a wearable computer with a screen above the right eye, goes on sale in 2014. Glass is almost certainly going to be used to support maintenance and repair calls, providing technicians (and other types of user) with the ability to access manuals and discuss situations with remote colleagues.
So are your user manuals, and the other content users might need to access, compatible with Google Glass?
Last night, I saw Joel Spolsky speak at a London Enterprise Technology Meetup, held at the London School of Economics. Joel is one of the founders of Stack Overflow, a hugely popular question-and-answer website on the topic of computer programming. He also claimed in a blog post back in April 2000, no-one reads manuals (see our article If no-one reads the manual, then why bother?).
So I asked him about his thoughts on the relationship between question-and-answer sites like Stack Overflow and traditional user documentation.