Business documentation Archives

guidelines for clear technical writing

Microsoft Manual of Style was produced in-house at Microsoft as the style guide for its army of writers who produce the help files and documentation for its products. Except that it’s been re-written for the public, and it’s completely non-prescriptive. They don’t say “This is the way it should be done”. They say “Here’s how we do it at Microsoft. You may find this approach useful”. It starts with a chapter describing the principles on which its house style is built – and these could profitably be adopted by any other organisation or business. Or any individual for that matter.

They are not at all particular to Microsoft, but aimed at producing seamlessly efficient communication. The principles include consistency of language, an empathetic attitude towards readers, precision, plain language, simplicity of sentence construction, a nod towards avoiding gender bias, and maintaining grammatical parallelism (which is very useful if you are writing instructions).

These issues are all illustrated by good and bad examples that show clearly the distinction to be made between for instance two apparently identical instructions::

Use this procedure to make any changes to your password.

Follow these steps to change your password.

The second has seven words instead of ten, less fuzz, and more clarity.

There’s a separate section on writing efficiently for the web. You should use the power of headings, sub-headings, bulleted lists, and well-chosen hyperlinks to maximise readability. There’s a specially valuable tip here. In each paragraph, put the conclusion first (what’s called the ‘inverted pyramid’ style) so that readers know if they wish to read on. People scan web pages rather than read them.

It’s not all about instructions and programs. The guidance assumes you might be using videos, blogs, and community-provided content such as wikis. It also keeps in mind that you might be writing for an international audience – but it points out that the guidelines for accommodating this are the same as for writing clearly and persuasively for English-speaking readers anyway. The maximum length of sentences should be twenty-five words.

For those people who will be writing about technology there’s a whole chapter on user interfaces – screens, menus, dialogue boxes, and toolbars – and how to write instructions that are clear and unambiguous. This is bang up to date, because to interact with contemporary devices you now need to include gesture (pich, swipe, zoom) as well as input via speech instructions and keyboard shortcuts.

More technical advice follows – on writing procedures (how to navigate through folders) how to describe cloud computing accurately, how to show code in support documentation, and fine details such as how to use filename extensions and when to use capitalization and bold.

There’s quite a lot on how to display numbers and when to use words (seven databases but a 24-hour day) how to show dates (February 12, 2012 – which is very non-standard) plus how to write captions and compile bibliographies.

On grammar and punctuation they understandably go for simplicity, clarity, and brevity. All the basic common sense rules are illustrated – but are then followed by some not-so-obvious but fascinating illustrations of indexing and list-ordering, including the order in which numerical entries will be listed. For instance 12-hour clock comes before 2-D charts.

There’s a huge list of acronyms with advice on when and when not to spell them out, and then the last half of the book is an alphabetical list of technical terms and commonly used words and phrases with illustrated explanations of good styling. They range from am/pm, through less and fewer, to ZIP codes and how to spell the plural of zero.

There are two indexes – one at the front and another at the back of the book – so it’s easy to find any detail you need to check. The latest fourth edition does its best to keep up to date with the ever expanding language of technology – app, cloud, and sync as well as terabyte (TB), petabyte (PB), and on up to yottabyte (YB). And it’s interesting to note that E-mail and Web site have now become email and website as these terms have now become part of everyday language.

Buy the book at Amazon UK