User Documentation

User documentation

Is needed to help people (the users) understand how to use a computer system or software application, such as a spreadsheet.

User documentation can be: Electronic (or “on-line”):

On-screen help menus E-mail support Telephone hot line Internet support

User documentation can be:

Paper or “print” based: Quick reference cards Comprehensive user

manuals Reference guides Brochures

Methodologies for producing documentation

What’s methodology? A methodology describes

the approach and the steps used to do things in a particular field.

Technical writers – the people who write user documentation – have methodologies for writing documentation

Standard documentation process

A widely accepted methodology for developing computer system documentation is the standard documentation process

The standard documentation process has a

number of steps

7. Update

6. Distribute

5. Produce

4. Test

3. Review

2.Draft

1. Plan

The standard documentation process

Using the standard documentation process enables you to develop user documentation in a methodical manner

The standard documentation process cont’

1. Planning:Investigate

Firstly, investigate the problem – what exactly is it that you need?

Eg. What is the purpose of

the document? Who are your audience? How detailed must it be? What exactly do you

need to explain?

1. Planning:Define the target audience

Who is the documentation for? Novice users? Intermediate users? Experts? Casual users? “Parrot” users? Transfers – eg from an

older version

1. Planning:Designing the documentation

This means structuring and presenting the documentation in a way that is: easy to use easy to navigate through is appropriate for your

users

1. PlanningDesigning the documentation cont’

The design should specify: Standards and styles

for text and graphics including typographic standards (eg Font sizes and types)

Topics Style and tone

For example, it is recommended that you use:

•A serif font such as Times New Roman for extended text

•Use 10 or 12 point font size

•Left justify

•Use sans serif font for headings and within tables or diagrams

•Use plenty of “white space”

2. Drafting

Drafting is the actual writing of the documentation and is the most time-consuming task.

The most important thing to remember in drafting is to make the documentation easily understandable for the user.

2. Drafting:writing style

The style of writing used is very important:

Use a conversational style – put things simply and clearly.

Use simple words – for example, use ‘carry out’ rather than ‘implement’, or ‘find out’ rather than ‘locate’

2. Draftingwriting style cont’

Keep paragraphs and sentences short

Make sure your spelling and grammar are perfect!

Be consistent – for example, don’t call a button a button on one page, and then call it an icon on another page

Use your spelling and grammar

checkers!

2. Draftingwriting style cont’

Use bolding, italics and capital letters consistently.

Don’t underline! Use bullets and numbers

where appropriate.

Don’t use fancy, hard-to-

read fonts

Use heading and sub-

heading styles consistently

3. Reviewing

Once a draft of the documentation has been done, it should be reviewed (checked) by another person

The reviewer should check areas such as: Does the document do what it set out to do? Have any areas been left out? Is the spelling and grammar correct? Are the instructions clear and easy to read?

3. Reviewing cont’

The drafting, reviewing, re-drafting, reviewing, process may continue through two or more redrafts.

Is the draft correct,

complete and clear?

Draft documentation

Review documentation

Yes

No

4. Testing

When the drafting and reviewing phases are complete, the documentation should be tested by potential users of the documentation.

If errors or omissions are found, the documentation will be redrafted and reviewed again.

5. Production

If the documentation is for use in a small organisation, production may just involve photocopying the finished documentation

For larger organisations or complex documentation, professional printing and binding may be necessary

In the case of electronic documentation, CDs may need to be burnt, or files uploaded to the internet

6. Distribution

Distribution simply involves making the documentation available to the people using the application or system it was designed for.

7. Updating

When a computer system or application is changed, the user documentation that accompanies it must also be updated.

Summary

User documentation can be electronic or paper-based The process of developing documentation should follow a

process that includes planning, drafting and reviewing When writing user documentation, certain conventions with

regard to style and typographic standards should be adhered to.

User documentation: Should be easy to read and understand Use short sentences and bullet points where appropriate Use graphics where possible (“a picture paints a thousand

words”) Use appropriate fonts Include page numbers, indexes / summaries where appropriate