Important note: your user documentation should explain how to re-use the solution in the future, not how the solution was created. You need to explain how someone should use the solution and produce the output. If, for example, you created a mail merge, you would not have to explain how you created formulae in the Excel data source or how you put SKIP IF statements in the form file. You would explain how to add/change/delete data from the data file and how to merge and print the revised letters.

Trying to explain how the solution was created will waste time and be irrelevant.

• 1 - Planning

• Example of planning

• 2 - Order

• Example of ordering main points

• 3 - Numbering
• 4 - Styles
• 5 - Presentation

• 5.1- white space

• 5.2 - icons

• 5.3 - screen shots

• 5.4 - graphics

• 5.5 - language

• 5.6 - colours

• 5.7 - fonts

• 5.8 - page format

• 5.9 - jargon

• 5.10 - details

• 6 - Testing
• 7 - Warnings

Also visit important related topics:

• Onscreen Documentation
• Electronic publications
• Qualities of good documentation

Plan the job first. Don't try to make it up as you go along - you'll end up in a mess. Jot down the main headings first. Worry about details later. Get all the top level headings sorted out first.

Decide on your format - is it better for it to be onscreen or printed? They involve quite different skills and considerations.

Important: ITA U4O1 must be onscreen documentation!

How to reuse the mail merge solution.

1. open the form letter.
2. edit the form letter
3. open the data file
4. add/delete/edit data
5. save files
6. preview the merge
7. carry out the mail merge
8. print the output
9. exit the programs.

Now you should make sure the main headings are in the right order. Make sure you explain how to do something before the user needs to do it. If the main headings have subheadings, you can insert those.

1. open the form letter
2. edit the form letter
3. open the data file
4. add/delete/edit data
   1. adding data
   2. deleting data
   3. editing data
   4. what to do if you add or delete columns/fields
5. save files
   1. file naming suggestions
   2. folder structure suggestions
   3. how to save
6. preview the merge
   1. using preview buttons
   2. warning about SKIP IF not working during preview
7. carry out the mail merge
   1. merging to a new document
   2. merging to the printer
8. print the output
   1. print options (e.g. number of copies, printing certain pages)
   2. how to start printing
9. exit the programs.
   1. warn about saving first
   2. how to close Word and Excel

Use the heading numbers as part of your documentation.

Vital Tip: use Word's autonumbering feature (Format > Bullets and numbering) and make sure Autonumbering is enabled (Tools > Autocorrect > Autoformat as you type > tick Autonumbered lists).

If you number paragraphs manually, deleting items will mean you will have to manually renumber the following points. Autonumbering will automatically update paragraph numbering as points are added or removed.

A common numbering format is like this

1. Main heading (level 1)

1.1 Level 2 subheading 1 of main

1.2 Level 2 subheading 2 of main

1.2.1 Level 3 subheading 1 of 1.2

1.2.2 Level 3 subheading 2 of 1.2

1.3 Back to level 2 subheading

2. Back to level 1 heading

Such a numbering scheme always makes it clear which topics are contained within other topics.

Type in the headings and subheadings. Leave the actual instructions for later. Note: you must provide some way for the user to find topics in your document: the minimum you need is clear headings. A table of contents or index is also useful, especially with larger documents.

Vital tip: Use Word's Styles if the documentation is to be printed. For the web, use heading styles in your web editor.

Word 2003 styles	Word 2007 styles (not as easy to use, I think)	Dreamweaver styles

You just have to type the heading, select a style (e.g. "Heading 1") Word will format the heading using that style (font, size, bold/italic etc). For the next heading with the same level of importance, you use the same style.

In this way, all of your headings have a consistent formatting and users can quickly find main headings and subheadings by skimming through the document.

Also, if you decide you want to use different formatting for your headings, you just change the style and all headings using that style are instantly reformatted.

Most importantly, you can generate a table of contents automatically if your headings use styles: you create a table of contents using styles (Insert > Index and Tables > Table of contents). Word will use the heading styles in the document to locate headings and subheadings and will make your table of contents from them.

Even better, if you add or delete headings, you can regenerate your table of contents with a single click of the mouse.

If you use both autonumbering and styles, imagine how much time you will save during the short period you get in class for creating the user documentation. Go forth and investigate both of these features forthwith!

Presentation

Getting the instructions complete and in the right order is only half the battle. Poor presentation can really hurt the effectiveness of your instruction manual.

Presentation includes these features:

white space

Lots of space on your page makes your documentation far easier to read. The white space visually separates topics and makes skim reading far easier. You may be given a word count for the documentation, but you don't have a page limit. You can use as many pages as you need, so don't be cheap when it comes to providing generous white space. Use nice wide margins to narrow the text width. Put at least one blank line between different points, and between graphics and text.

icons

Consistent use of meaningful icons greatly helps the reader. Icons draw the reader's attention to certain types of information. The reader can be skim-reading and relevant icons will draw their attention to what they want to find.

For example, say the reader is quickly skimming the documentation, but wants to be made aware of urgent warnings. A neatly placed skull and crossbones icon will alert them to potential danger. Say another reader, who knows the basics of the task, is skimming for useful tips and hints: the "lightbulb" icon makes such handy hints easy to find.

Don't overuse icons - having icons for no purpose reduces the value of all the other significant icons. Use them with discrimination and they have high information value.

screenshots

Your task with documentation is to convey maximum information in minimum time. The use of appropriate screenshots can greatly help your explanations. Trying to describe some buttons in Word, for example, can be difficult, wordy and inaccurate. It would be far better for both you and the reader to say "Click this button" and have a picture of it. A picture can really be worth a thousand words. It's a win-win situation: you save words, the message is clearer, and the reader saves time and confusion.

Don't put in trivial screenshots - use screenshots that actually convey useful information.

There are several screenshot utilities available that let you snapshot windows or regions. If you don't have such a utility on your network, have a word to your IT teacher: you won't regret it.

If you don't have a screenshot program, the only alternative is to dump the whole screen to the clipboard (press the PRINTSCREEN key), start up a paint program and paste the image from the clipboard to the paint program. Crop the image to isolate the feature you wanted to show. Save the image and insert it into the document. To capture the active window, press ALT+PRINTSCREEN.

Many free utilities do screenshots, such as XNview (a great freeware picture viewer, slideshow/webpage maker, batch picture processor)

graphics

The use of attractive decorative graphics, such as dividers, can make the documentation more pleasant to read and can help divide it into sections. Use them in moderation, though. They should not be irrelevant, offensive, or distract from the main purpose of the documentation. Like these perhaps...

spelling, punctuation, grammar, expression

If you are an ESL student, or you write as if English was your fourth language, you will need to pay special attention to the accuracy of your writing. Inaccurate spelling, punctuation, grammar or expression will make your meaning less clear or possibly confuse the reader. Think of the frequent "Jinglish" instruction sheets you get with some backyard foreign manuals where you're lucky to understand one sentence in five. Try these for size:

From a transceiver manual: "replace R23 with a 50 K ohm lesistor."

From the manual to an monitor: "Contrast knob will make picture bright but not dazzling."

And a maxim we can all live by: "Keep off the capacity transformable or magnetic."

From an old AutoCAD manual: "Undoing a Redo will redo the original Undo."

Click here to see a fairly typical manual from a Taiwanese video card maker

Use the spell checker to find mistyped words. Beware of words you know you confuse (e.g. "its" versus "it's"). Express yourself simply: don't try to use impressive words to show off: you will get them wrong and look stupid. The aim is always to provide the maximum amount of clear information in as few words as possible.

colour schemes

If you intend to print in colour, make sure your colours are readable and don't obscure your text. Colour can be a useful tool to identify types of discussion, e.g. red for warnings.

font choices

No more than 2 font faces per page. Use them consistently, for a clear purpose. Showing off how many fonts you have on your computer is immature and unimpressive.

page size and format

Documentation often comes in book form, but it can come in different formats for different purposes. If you feel a small pocket-sized format would be more logical, do that. If a poster is the best format for presentation, do that. You don't have to stick to using flat A4 pages.

jargon and big words

Jargon is specialist language used by people in an area of knowledge - e.g. pilots, doctors, skateboarders. It is a shorthand way of expressing difficult concepts. Jargon in itself is not bad: it's how you use it and to whom you use it.

A doctor at a medical conference would not talk about the "tummy". But if the doctor were talking to a small girl, he or she would not refer to the gastric region. Language is appropriate if it is suitable for the audience it is used for.

You should be told who the audience for your documentation will be: it is important because it can completely change the way you express yourself. A common audience for this SAC may be "Year 12 students who are not doing IT - they have fair computer knowledge but know nothing about mail merge".

If you were writing for complete beginners, you would need to explain more terms and give more precise step-by-step details on how to do something. If you were writing for experts, you would provide fewer explanations and less detail.

Some terms may be unavoidable: the reader should be told what they mean because it's important. If you feel a reasonable reader would not be likely to know a term, explain it the first time you use it. This applies to acronyms too: words made up of initial letters of a name or phrase (e.g. CSIRO, QANTAS, RAM, USB). The first time you use the expression, say what it means and thereafter you can use the expression freely.

If you can choose between using a big word and using a clear short word, use the short one. It will aid the readability of your writing and let more people use it.

Level of detail

How much detail to put into any documentation can be a tricky decision. It depends on the skill level of the audience, the dangers inherent in the task, the number of words or amount of time you have available to do the writing.

Whatever, you must make sure you cover the entire topic of how to re-use the solution you created in the SAC. Make sure you don't leave out vital sections such as producing the output.

In real life, you would take your finished draft documentation to a typical audience member and test it: you would get the victim to carry out the instructions to perform the task. You would take note of errors and confusion and find out what weakness in the documentation led the victim astray.

You can test it yourself by playing the 'Stupid Robot Game'. Go into brainless mode and read your instructions as if someone else had written them. Do exactly what the instructions say - no more, no less. Don't "fill in gaps" where you know what the author meant to say but didn't. Can you satisfactorily re-use the solution? Can you produce the necessary output? If not, fix the relevant instructions.

If there is any action that could cause grief to the user, they should be suitably warned before the danger strikes. Saying "Now click the EXIT button - oh, by the way, make sure you save first" is a dangerous piece of foolishness.

Information in the documentation must be easy to find.  Use logical ordering, and a table of contents or index.

Good content is:

• current (up to date)
• clear (easily read, easy to understand)
• concise (as short as possible without leaving things out)
• complete
• correct

Use pictures to make explanations clearer, and to save words.

Warn of possible dangers before the dangerous action is described.

Test the documentation on yourself, on another skilled user, and on a typical naive user.

For practice, try writing instructions on how to:

• How to play Solitaire
• How to crop an image in Photoshop
• Using CSS in Dreamweaver