New online Microsoft writing style guide

Microsoft has released the latest edition of its writing style guidelines as a website:

writing style guide banner image

“Welcome to the Microsoft Writing Style Guide, your guide to writing style and terminology for all communication—whether an app, a website, or a white paper. If you write about computer technology, this guide is for you.

Today, lots of people are called upon to write about technology. We need a simple, straightforward style guide that everyone can use, regardless of their role. And it needs to reflect Microsoft’s modern approach to voice and style: warm and relaxed, crisp and clear, and ready to lend a hand.

The Microsoft Writing Style Guide replaces the Microsoft Manual of Style, a respected source of editorial guidance for the tech community for more than 20 years. The style guide features updated direction and new guidance for subjects that weren’t around when the last edition released. But it’s also a reimagining of Microsoft style—a tool to help everyone write in a way that’s natural, simple, and clear.”

It’s available for anyone to use, especially Technical Authors.

See: Microsoft Writing Style Guide

Don’t say “simply”

At this month’s WriteTheDocs London meetup, Jim Fisher of Pusher presented a talk called “Don’t say Simply“.  He talked about words, such as “simply”, that can seem innocuous when written in user documentation, but which show a lack of sympathy when read.

He showed how popular “simply” is with developer documentation writers, by showing the number of hits for that word in GitHub: 93 million! If you restrict the search to Markdown files (the file type on GitHub used mostly for documentation) , it’s 3,325,386 hits.

“Easy” and “easily” are also problematic, and overused: There are 4,127,104 Markdown pages on GitHub for “easy”, and 2,797,143 Markdown pages for “easily”.

The problem with “simply” and “easy” is that the related task or concept is unlikely to be always simple or easy when the reader needs to read the documentation.

These words are typically “banned” in the main technical writing style guides, but they could be appropriate in training or marketing material. In general, it’s best Technical Authors avoid them.

Here is a link to Jim’s slides: Don’t say “simply” (Write The Docs London, 2018-01-23).

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…