This page has 0 threads | Add post

How to write computer training manuals and user guides

Writing good technical documentation isn't easy, but below are some simple guidelines you can follow to avoid the worst traps.

For the bible on how to write good English, see The Economist's style guide.

Guideline 1 of 4 - use the active tense

The passive tense should be avoided at all cost! Here are some good and bad examples of simple instructions:

Bad sentence	Better sentence
"A chart will be created in Excel"	Excel will create a chart
"Your paragraph will now be centre aligned on the page"	Word will centre align your paragraph on the page
"Good form design will be appreciated by users of your system"	Users of your system will appreciate good form design

Changing the passive tense into the active makes sentences shorter and easier to understand!

Guideline 2 of 4 - keep your paragraphs short

Consider which of the following two instructions you find easier to read.

Paragraph 1:

To create a custom number format in Excel, simply select the cells whose format you wish to change. You can then select Format Cells from the menu. Finally, complete the dialog box which appears as shown below, then click on OK.

Or paragraph 2:

To create a custom number format in Excel:

Select the cells whose format you wish to change.
From the menu select Format Cells.
Complete the dialog box which appears as shown below, then click on OK.

We hope you'll agree that the second box is much easier to read, because it breaks the text up into numbered paragraphs.

Never allow more than 2 lines of text at a time - use tables, numbered steps and (above all) diagrams to break up long passages of text.

Guideline 3 - use diagrams wherever possible

A picture, it is said, is worth a thousand words, but this understates the truth. Consider this diagram, and imagine how long would it have taken to explain all of this in words alone:

As it happens, this shows indicators in SQL Server Reporting Services.

Wise Owl recommend TechSmith's SnagIt screen capture programme for getting screen dumps, and Microsoft Word for producing manuals - provided that you can cope with Word's foibles, that is!

Guideline 4 - use simple words

If you want to show off your vocabulary, write a novel. If on the other hand you want to write good, clear English which is easy to understand, use simple words.

Here are some words to avoid:

Bad word	Example	Better
Endeavour	"You must endeavour to use short words"	Try
Very	"Excel is very easy to use"	Miss it out!
Employ	"You can employ lots of techniques in Excel to format cells"	Use