Microsoft moves away from “robot speak” in its user documentation

DSC00498One of the highlights from the Technical Communications UK 2014 conference was the keynote presentation from Microsoft’s Doug Kim. Doug is Senior Managing Editor for Office.com, and leads guidelines and best practices for Voice in Office. By Voice, he means the tone of voice and style of English used in the User Interface and user documentation.

Doug Kim at TCUK14

The change in voice is something we explore on our advanced technical writing techniques course, so I was interested to see how Microsoft was addressing this topic. The good news for us is that Microsoft’s approach is consistent with what we advocate on the course (however, we will need to update the course before the next one in December to include some of the topics Doug discussed).

Continue reading

Is it time for a new writing style in technical communication?

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?

See also:

Voltaire, typos, and the jitters – writing the IBM Style Guide

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…

Microsoft Style Guide for Windows 2007?

We received this email yesterday:

Microsoft Style Guide for Windows 2007
Do you know whether such a thing exists or whether you know of anything else that might help? I am updating the help for our new product and it uses a Windows 2007 ribbon style GUI but I don’t know what all the elements are called.

The Microsoft Guide of Style was written in 2004, so it’s a case of looking elsewhere. We suggested the Microsoft Office Word team blog, which has some useful information on this.

Web 2.0 style guides

We recieved an email asking:

“I have just started at this software company, and one of my tasks is to work on the writing style guide. I have been looking around on the Internet for a style guide that covers writing style for web applications (or interfaces), and am wondering if you could point me in the right direction. I am looking for a style guide, preferrably in the public domain, that recommends how web-based user interface items should be written in software manuals.

I’ve looked at a number of company style guides including Microsoft, Sun, and IBM. However, with traditional interface tools like buttons and menu items evolving with the emergence of more sleeker web-based interfaces (rather than the standard dialog boxes that have been around for some time), I was wondering if any software company (or group), besides the ones mentioned, have come up with more up-to-date descriptions of some of these items in their style guide. I would be very happy if you could offer some advice here.”

It’s a good question. Does anyone know the answer?