What a Lot of Fonts

The introduction of desktop publishing and the development of word processing have revolutionised documentation production. Now, virtually anyone can create professional-looking documents of all types.

But many people get carried away with the huge range of fonts and features that are now available. They use a variety of fonts, apply bolding and italicising with abandon, and scatter clipart and icons like confetti. And the result is an awful mess.

If this is you, then write 'I must learnt to keep it simple' one hundred times before you start. Then:

• use no more than two typefaces — Arial for headings, Times Roman for body text, for example.
• apply boldface and italics sparingly and consistently. Thus, you may use bold for emphasis and italics for the titles of cross-referenced documents.
• add graphics only if they serve a purpose — diagrams to illustrate document flow, icons to identify advice and warnings.

Break It Up

User documentation should be 'user friendly', to use a very overworked phrase. It should provide information and advice in a friendly and helpful style.

Avoid large slabs of unbroken text. They are unwelcoming and do not encourage reading — and long sentences and paragraphs are difficult to read and understand. Instead:

• use bullet points and numbered lists
• have input tables to describe data that needs to be entered
• emphasise words and phrases by bolding and italicising (use sparingly)
• incorporate icons to highlight important points and 'hints'
• provide diagrams to illustrate workflows and structures
• use sample screens and buttons where appropriate.

Not Just Looking Good

There is a worrying tendency to value style above substance — if something looks good, then it must be good. But is it? Obviously not.

To be any good at all, user documentation must be useful. It must provide information and advice. It must help users to do their job properly. If it fails in this purpose, then it is pointless — no matter how good it looks.

With the advent of HTML, the Web, and all that goes with them, too many people seem to think that spelling, punctuation and grammar have little importance. This may be true with e-mail, where informality reigns. But for formal documentation, accuracy in all things is still important.

How many documents, advertisements and Web pages do you see, where the overall effect is ruined by incorrect grammar and punctuation? The correct placing of apostrophes seems to be a dying art. Indeed, the modern rule seems to be: 'if in doubt, add an apostrophe'.

Who Are You?

Many user manuals give the impression that the author doesn't know who the document is aimed at. They refer to 'the user' as though this is some mythical being on a par with the Loch Ness Monster or the Abominable Snowman. 'The user' is actually the person who reads the documentation and must be addressed appropriately. Simply replacing 'the user' with 'you' is not a bad start.

An even worse fault is when manuals use phrases such as 'the user will.....' or 'an update is undertaken by the user....'. Whenever possible, all instructions should be written in second person, active voice. Thus, 'enter the customer's account code' instead of 'the customer's account code is entered by the user'. This is not only more direct and personal, it actually uses less words.

If It's Not Worth Saying, Don't Say It

How many times have you seen manuals that say something like the following?

This is a waste of time, effort and space. And, instead of helping the readers, it's more likely to convince them that the documentation has limited use. It's better to say nothing than to make a meaningless or pointless statement. Don't state the obvious and don't insult the reader's intelligence. Manuals have gone in the bin for less.

Even worse, manuals sometimes say:

How are these codes used? What values are permitted? Are the valid codes defined elsewhere? If so, where are they? How should the codes be allocated?