1

User Documentation

2

Purpose of User Documentation

Understanding Training Reference

So…who uses Documentation in the IT industry?

Where do you fit – in which of these roles do you see yourself?

3

A general methodology has the following steps:

Planning Drafting Reviewing Testing Producing Distributing Updating

Refer to Methodologies.doc

4

Types of User Documentation…

5

Printed documentation

Manuals Handbooks Quick Reference Guides Keyboard Templates Wall charts Training manuals Policies and procedures

Think of an example of each of these that you have seen here at TAFE

6

Computer based documentation

On-line versions of printed software. Windows help files On-line tutorials Computer based instruction Wizards Glossaries (Eg: screen tips) Context sensitive help Troubleshooting guides

7

Web-based documentation

Web-based documentation has the advantage that it can respond to the needs of users much more quickly than static (print or CD-ROM) documentation.

8

Common forms of web-based documentation are:

Manuals: a down-loadable file (generally in Adobe Acrobat,

Microsoft Word or plain text format) HTML version, around which the user can

navigate directly with the web browser. Frequently asked questions (FAQs) User forums - message boards or

newsgroups

9

DEVELOPING USER DOCUMENTATION

You have already come a long way in the process of developing user documentation.

You learned that blueprinting is a stage of developing user documentation for a product…lets apply that to our 2 button scroll mouse example

10

Mouse OperationsThis reference card is intended for users who are new to mice.Holding the mouse•The tail of the mouse should point away from you.•Keep the heel of your hand on the mat.•Hold the palm of your hand over the body of the mouse.•Hold one finger lightly over the left button.•Hold another finger lightly on the right button.•Always watch the screen, not the mouse.Clicking•Move the mouse pointer to where you want to click.•Press and release the left button.•Don't move the mouse between press and release.Right clicking.•Move the mouse pointer to where you want to click.•Press and release the right button•Don't move the mouse between press and release.Double click•Move the mouse pointer to where you want to double-click.•Press and release the left mouse button twice.•Keep the mouse still while you click the buttons.Click & Drag•Move the mouse pointer to the item you want to drag.•Press the left button and hold it down.•Move the pointer to where you want to drag the item.•Release the left mouse button.

11

User categories

Not all users are the same! The publishing world generally recognises three levels: novice (beginner), intermediate and

expert. Another way to classify users is by level of

interest. Someone who is reluctantly learning to use a workplace application will have a very different approach from that of an enthusiastic hobbyist.

12

Documentation design

Your blueprint should already address issues of document design, but it is worth

giving them another thought before starting to draft a document.

13

Are there organisational or project

standards? What font, size and style of lettering will be used for the body text of the document, and for various levels of headings?

What will be contained in headers and footers? How will the pages be numbered? How will illustrations be handled? Will the document be printed in colour? What size are the pages?

14

What topics will the document cover? In what order? In what level of detail?

What will be the tone of the document? Formal or chatty? Serious or humorous? These factors will heavily influence the way users see and respond to your document.

What is appropriate is often culturally dependent. If you are writing a document for use in cultures other than your own, take care.

15

There are many principles of document design that were known

to printers and publishers long before computers came into

existence. They exploit the way human vision works when it is

reading text.

16

ISSUES OF STYLE

17

Language tone

The best choice for user documentation is usually warm and personal, in order to humanise the learning experience as much as possible.

Avoid straying too far into informal language, as this could destroy the sense

of authority and reliability that documentation should have.

18

Here are some examples of the same information conveyed in different tones:

“Failure to adopt the correct shutdown procedures may result in data loss.” (formal, official and unfriendly)

“If you don’t shut down your computer correctly, you may lose unsaved data.” (more friendly and personal)

“Don’t just switch off – you could lose data!” (less formal, but does not specify what to do instead)

Which do you prefer?

19

Jargon

Information technology is particularly notorious for jargon.

Jargon should be avoided as much as possible in user documentation.

20

Simplicity

Avoid using a long word or phrase where a short word will do just as well.demonstrate - showcommence - startlocate - findwith regard to - aboutat the present moment in time – now

In a similar way, you should try to keep sentences reasonably short and simple.

21

Clichés and slang

Both these forms can be very difficult for readers who are from a different culture than the writer. When you are writing for a general audience, there is no place for them. Try to avoid them in writing computer documentation.

“the bottom line”, “leave no stone unturned”, “lead by the

nose”, “doesn’t have a leg to stand on”, “my shout!”

22

To be comfortable with clichés, you need to be very much a part of the culture in which they are used.

Slang is even more culturally dependent. It also varies from time to time and with the age of the speaker. Different groups within the same community may use different forms of slang.

23

Spelling and grammar

Documentation with poor spelling and grammar detracts both from the author and from the product it documents.

A particular problem in English is that spelling (and some grammar) differs from one dialect to another. You will probably be familiar with the differences between American spelling (color, traveler, center) and British/Australian (colour, traveller, centre). Your choice should depend on your target audience.

24

Avoid the temptation of relying too much on automatic spelling checkers to find incorrectly spelled words.

All they do is check that every work you use is in the dictionary; they cannot cheque that words are used correctly.

25

I have a spelling chequer

It came with my pee see

It plane lee marks for my revue

Miss steaks eye cannot sea

Each thyme when aye have struck the quays

I weight for it to say

If watt eye rote is wrong or rite

It shows me strait a weigh

A spelling checker shows no errors in this text!!

26

Voice

If you are describing something or telling a story, English has a choice of two voices, active and passive.

Active voice is more direct, and means the subject carries out the action – it is shorter, simpler and easier to follow

Eg: Check the data for errors, then press the enter key

27

Consistency

It is important to maintain a consistent style throughout a document. Consistency applies to many aspects of the document:

Use a consistent tone. Use consistent layout. Use consistent spelling.

28

Foreign language considerations If you are writing documentation for a product that will

be used outside the English-speaking world, don’t make the mistake of thinking that the English documentation will do.

Even if the users of your product know English well, they will appreciate documentation in their own language. If there are many such users, you should provide a translation.

Be aware also that different languages (and different

dialects of English) use different ways to represent dates and numbers.

29

Standards

http://www.iso.org/iso/en/prods-services/CatalogueListPage.CatalogueList

Standards are guidelines for producing documentation. You will need to know when producing documentation if there are standards you should be following!

They ensure quality and consistency of documentation, and can be classified into 3 types:

• Industry standards

• Organisational standards

• Project standards