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.

 

Technical communication as a brand – The CEO and the technical communicator

The CEO and the technical communicator ebookSince I wrote the post on Technical communication as a brand, we’ve been working on an idea we had for promoting the profession. The end result is another story, another free graphic novel you can download, called The CEO and the technical communicator.

It’s published under a Creative Commons licence, so anyone can forward it on, as long as they don’t modify it or sell it.

There’s a lot of factual evidence about the value of technical communicators to an organisation (such as the ROI calculators on our website), so we thought we’d see if we could appeal to the heart as well as the head by using a story-based approach.

Technical communication comes in many forms, so there were some challenges in coming up with something that was representative of the whole profession. Partly to get around this, the document shows people’s reactions to the content created, rather than showing the content itself. It also uses the word “content’ as a catch-all for document, manual, book, Help file, Web page, illustration, and so on.

We’ve also developed an ISTC-branded version that the Institute for Technical Communicators could use itself to promote the profession. We’ve sent it to to the ISTC Council for their consideration and comments. The document might be modified if they ask for any changes to be made; for example, we’re wondering if there should be greater emphasis on the writing aspect of the role.

You can download the Cherryleaf version from our website. Let us know what you think, using the comments below or by email.

The big questions in technical communication

David Farbey wrote a semi-existentialist post on the challenges for technical communicators yesterday. I’d like to look at the issue in a different way, by looking at the big questions in technical communication today. The answers to these questions (which may be decided by people outside of the profession) are likely to affect the future direction for technical communicators.

Continue reading

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

Technical Communicators and their Websites

STC Notebook blogI’ve just written a new post for the STC’s Notebook blog on Technical Communicators and their Websites.

We look at some of the challenges and decisions technical communicators face when designing a website for their business. To help illustrate this, I included some examples of technical communication companies’ websites, including our own.

“Engaging your readers in the documentation. How and why social media?”

Sarah Maddox (Technical Writer, Atlassian) is another champion of engaging readers through technical documentation.

Here is a video of her presentation to the Atlassian User Group Wiesbaden. It’s called “Engaging your readers in the documentation. How and why social media?”

See also