The Government Digital Service has published an interesting guide on writing copy for User Interfaces and transactional interfaces:
While there have been huge leaps in the technology used to create and publish user documentation, it’s been quite a while since there were any serious changes to the writing style in technical communication.
Here is a rough timeline for technical communications standards, according to xml.org:
- 1961 Quick Reader Comprehension (QRC)
- 1963 Hughes STOP – (Sequential Thematic Organization of Publications)
- 1967 Information Mapping
- 1974 SGML
- 1982 Information Types
- 1990 Minimalism and task orientated instructions
See also History of technical communication in 7 minutes video.
The writing style has essentially remained the same for at least 20 years.
So what about DITA – isn’t that new? DITA was introduced around 2002 (and approved as a standard in 2005), but it’s more about structuring and organising information around Information Types such as task, concept and reference. Is the style of writing for DITA any different from the writing style for minimalism?
With the new insights we can gain from web analytics, psychology and other data, is it time to see if we can make improvements to the writing style used by most technical communicators?
This guest post is from Peter Hayward of IBM (UK):
Voltaire said that “the art of medicine consists in amusing the patient while nature cures the disease.” Technical editing is a bit like practising medicine. It has a focus on both prevention and cure, except we don’t have nature on our side. With editing, nature tends to maintain the status quo; if the doctor doesn’t attempt the prevention and provide the cure, the disease persists. Writers need some sort of guidance to help them through the minefield of trying to write consistently, clearly, and concisely, while still following all the rules that editors seem to enjoy imposing.
Like many organisations, IBM has made up its fair share of rules and guidelines. A council of about 15, drawn from across the company’s writing community, is charged with looking after them, making sure they stay consistent and up to date. These guidelines have been available internally for many years, but we recently recognised that this accumulated wisdom might have a use in the wider world of technical writing.
So a sub-group of editors from that Style and Word Usage Council set about turning the guidelines into something fit for publication, removing all the boring internal bits, making sure we didn’t upset any sensibilities, or run foul of our legal overseers.
IBM uses DITA markup these days for most technical documentation, so we decided to follow suit with our scribblings. As well as providing our text to the publishers in that format, we were able to transform it daily into HTML and put it in a structured help system (“information centre”) based on Eclipse so that we could keep track of what we were doing.
I guess that to a big publisher, our little book was just one more title on their list. We naturally saw it as much more. Although, thinking about it, such a book actually is different from other titles, which is making me just a little apprehensive. If you want to use trendy jargon, you could say it’s a “metabook”, writing about writing, which means that you’re inevitably setting yourself up for a fall. If you spot a typo in most books, it’s usually little more than an annoyance. Typos and mistakes in books that purport to tell the reader how to write properly, invite a rather different response.
So if you do get your hands on a copy of the IBM Style Guide (“available from all good bookshops”), please be gentle. We tried to persuade the publishers that it was you, discerning author, who we were writing for, and not your average “punter”. OK, so it’s not fair to pass all the blame for errors to these editors’ editors. But I’m a little nervous. Of course it’s full of good stuff, well written and without blemish. Really it is. But I just have this feeling, that as the very first copy I handle falls open at random…