Why “What are good and bad examples of technical writing?” is a difficult question to answer

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:

  1. Adopting an action-oriented approach (to minimise the amount of reading)
  2. Starting immediately on meaningful tasks
  3. 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.

 

Design-led technical documentation

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.

Continue reading

Our next Advanced Technical Writing Techniques course – 24th April 2014

After a short break, our Advanced Technical Writing Techniques training course has returned. We’ve scheduled a public course for Thursday 24th April 2014, in South Kensington, central London.

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.

Discover the advanced new writing styles emerging in technical communication. Don’t get left behind. You can book a place via the webpage Trends in Technical Communication Workshop – Advanced Technical Writing Techniques.

The roofer who makes £400/day because he read the Velux installation guide

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.

Are your user manuals (and any other content) ready for Google Glass?

Google_Glass_detail from WikipediaGoogle 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?

Continue reading

What does Stack Overflow’s success mean for traditional User Assistance?

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.

Continue reading

Proving your technical content is the most important content on your website

In yesterday’s post, How technical content on the Web is turning traditional marketing strategy on its head, we discussed the importance of technical content to today’s marketing funnel. You might be thinking, show me more evidence.

Continue reading

How technical content on the Web is turning traditional marketing strategy on its head

Kathy Sierra famously summed up most marketing departments’ approach to content in this slide:
kathy sierra - How we treat customers

To paraphrase her, the website and brochure are a thing of beauty, while the user manual is a thing of boredom.

Today, the way people use the Internet means this approach to marketing needs to change

Continue reading