Important note: in the 2011-2014 study design, both IT Applications and Software Development have user documentation as part of U4O1. Note that the ITA.

By Mark [email protected]

Vceit.com

VCE IT Lecture Notes

Writing User DocumentationFor ITA U4O1 and SD U4O1

Important

Important note: In the 2011-2014 study design, both IT Applications and Software Development have user documentation as part of U4O1. The ITA user doc must be onscreen documentation, created with web or multimedia software. In SD it need not be onscreen, and you use "appropriate" software.

Note

• Important note: your user documentation should explain how to re-use the solution, not how the solution was created.

• You need to explain how someone should use the solution and produce the output.

• Do NOT explain how to name cells or do VLOOKUP!

• You would explain how to add/change/delete data from the and how to print, save and exit.

PLANNING DOCUMENTATION

• 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.

• If you have a choice, decide on your format - onscreen or printed? (ITA is onscreen; SD does not have to be)

Minimum Contents

1. How to open the solution.2. How to enter new data3. How to change data4. How to save data5. How to produce output6. How to exit the solution

Planning exampleHow to reuse my mail merge solution.• Open the form letter. • Edit the form letter• Open the data file• Add/delete/edit data• Save files• Preview the merge• Carry out the mail merge• Print the output• Exit the programs.

Then

• Now you should make sure the main headings are in the right order.

• Organise subheadings under main headings.

1. open the form letter2. edit the form letter3. open the data file4. add/delete/edit data

1. adding data2. deleting data3. editing data4. what to do if you add or delete columns/fields

5. save files file1. naming suggestions2. folder structure suggestions3. how to save

6. preview the merge 1. using preview buttons2. warning about SKIP IF not working during preview

7. carry out the mail merge 1. merging to a new document2. 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 first2. How to close Word and Excel

Numbering• Use numbered headings as part of your

documentation.• Use autonumbering where possible.• If you number paragraphs manually, deleting

items will mean you will have to manually renumber all of the following points.

• Autonumbering will automatically update paragraph numbering as points are added or removed.

Numbering

A common numbering format is like this1. 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 subheading2. Back to level 1 heading

This makes it clear which topics are contained within other topics.

Getting started• Enter the headings and subheadings. • Leave the actual instructions for later. • 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. These can be created automatically if you use heading styles.

Automated heading styles

Office 2003

Office 2007

Dreamweaver

Why use heading styles?

• In Word, you can create automatic indexes and tables of contents.

• Word uses heading styles.• If you add or delete headings or sections, you can

regenerate your table of contents with a single click of the mouse.

Why use heading styles?

• The software will format the heading using a consistent style (font, size, bold/italic etc).

• Users can quickly find content by skimming through the document looking for headings by their appearance.

• If you decide to change heading formats, you just change the style and all headings using that style are instantly reformatted.

Design Elements

Elements related to functionality are • Structure• Usability • Accessibility (for those with disabilities)• Navigation and load time• Appropriateness• Relevance.

Presentation

• Poor presentation can really hurt the effectiveness of your user documentation.

• Remember the design elements relating to appearance:– proportion (visual hierarchy)– orientation (direction/ aspect)– clarity and consistency– colour and contrast.

White Space – done badly

Lots of space on your page makes your documentation easier to read.White space visually separates topics and makes skim reading far easier.Use nice wide margins to make the text width narrower. Short lines are easier to read.Put at least one blank line between different points,and between graphics and text.

White Space – done well

Lots of space on your page makes your documentation easier to read.

White space visually separates topics and makes skim reading far easier.

Use nice wide margins to make the text width narrower.

Icons• Consistent use of meaningful icons greatly

helps the reader. • Icons highlight certain types of information. • The reader can find desired information (e.g.

warnings) by scanning for icons.• E.g.

Icons

• Warning

• Tip

• Here’s a link

Screenshots• Pictures convey maximum information in minimum

time. • Trying to describe some buttons in words 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. • It's a win-win:

– you write less– the user has less to read– the message is clearer– It saves the reader time

Screenshots• Use dedicated screenshot utilities where possible.

They can include the mouse pointer in the image, autosave and autonumber shots, crop etc.

• Or use the PRINTSCREEN key and paste the image from the clipboard to the paint program to process it.

• To capture the active window, press ALT+PRINTSCREEN.

Then you can edit it in a graphics editor

Decorative Graphics

• Decorative graphics, such as dividers, can make the documentation more pleasant to read and can help divide it into sections.

• Use them in moderation. They should not be irrelevant, offensive, or distract from the purpose of the documentation.

Grammar, expression• Don’t confuse the reader.

– "replace R23 with a 50 K ohm lesistor.“– "Contrast knob will make picture bright but not

dazzling.“– "Keep off the capacity transformable or

magnetic.“– "Undoing a Redo will redo the original Undo."

Spelling

• Use the spell checker. • Beware of words you know you confuse (e.g.

"its" versus "it's"). • Use simple expression and short sentences. • Don't try to use impressive words to show off:

you will either get them wrong and look stupid, or your reader won’t understand you.

Colour Schemes• Overlapping colours must have good contrast.• Don’t use red/green or other colourblind

combinations.• Text on photos can become unreadable• Colour can be a useful tool to identify types of

discussion, e.g. red for warnings.

Typefaces• No more than 2 typefaces per page. • Use them consistently, for a clear purpose

– e.g. Arial for headings, Times New Roman for body text.

• Showing off how many fonts you have on your computer is immature and

unimpressive.• NEVER use decorative typefaces (e.g.

gothic) for body text!• Keep font sizes big enough to read

Printed page size and format

• Printed documentation is often in book format.

• Other formats for different purposes. – Pocket-sized format?– Wall poster?– Leaflet?

Jargon• Jargon is specialist language used by people in an

area of knowledge - e.g. pilots, doctors, skateboarders, IT workers.

• It is a shorthand way of expressing specialist concepts.

• Jargon is not bad if used with people who understand it.

• Know your audience: avoid or explain jargon used with non-expert readers

Jargon

• Explain in more detail if readers might be complete beginners

• If jargon is really needed to save time, explain the term when you first use it.

Use simple words instead of big ones

GOOD BAD

Use Utilise

Now At this point in time

Do Accomplish

Find Out Ascertain

Try Endeavour

Help Facilitate

Place Locality

About With regard to

By By means of

If In the event that

Too Many Excessive number of

Or avoid words altogether

How much detail?

• Can be a tricky decision. • It depends on things like:– skill level of the audience– the dangers inherent in the task– the complexity of the topic

• Make sure you cover the entire topic and don't leave out vital bits like producing the output.

Testing

• Take your draft documentation to a typical audience member to test it. – Get the victim to carry out the instructions.– Take note of errors and confusion and fix those

bits– Ask them to carry out an action described in the

documentation.

TestingTest it yourself by playing the 'Stupid Robot

Game'. – Carry out the instructions as if someone else had

written them.– Do exactly what the instructions say - no more, no

less. – Don't "fill in gaps" where information is missing.– Can you satisfactorily re-use the solution? – If not, fix it.

Warning!• If there is any action that could cause grief to

the user (e.g. data loss), 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.

FinallyInformation in the documentation must be

easy to find. • Logical organisation• Headings• Numbered sections• Electronic search facility

FinallyGood documentation is:• current (up to date)• clear (easily read, easy to understand) • concise (as short as possible without leaving

things out)• complete• correct

Finally• Use pictures where possible.• Warn of possible dangers before the dangerous

action is described.• Test the documentation.• For practice, try writing instructions on how to:– How to play Solitaire– How to crop an image in Photoshop– Using CSS in Dreamweaver

By Mark [email protected]

These slideshows may be freely used, modified or distributed by teachers and students anywhere on the planet (but not elsewhere).

They may NOT be sold. They must NOT be redistributed if you modify them.

IT APPLICATIONS SLIDESHOWS