user documentation created by vitta modified by d.lupone using text book potts et.al (2007)

User Documentation

Created by VITTA modified by D.Lupone using text book Potts et.al (2007)

User documentation

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

User documentation can be: Paper or “print” based

Quick reference cardsComprehensive user manualsReference guidesBrochures

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

On screen user guides and instructional manuals

• PDF• Hypertext

Quick Start Guides• Brief text in Hypertext• Screen shots• diagrams

In-house documentation– User guides or

instructional manuals about how to use the

• Information system• Protocols• customised databases,

spreadsheets…

Read Me Files

Tutorials• Step by step instructions• PDF or hypertext• Multimedia (sound and

video)• Can be on CD/DVD or

downloadable from manufacturer’s website or other sites such asYouTube

On-screen help menus• Searchable by content or

alphabetic index or by typing a question into a search field

• Case-sensitive help e.g. starting a word may trigger a dialogue box

• Utility program may come with the software or hardware to help you set things up

• Tool tips and hint boxes

Web support• Usually a hyperlink to

manufacturer’s website comes with product.

• Contains sections such as• FAQ• Knowledge base• Troubleshooting• How to upgrade your

product• Tech talk –solutions or

patches for known software bugs

• Community or forum-based websites

• Users of product contribute advice they share freely

• Blogs – where an individual records personal comments.

Or…

Methodologies for producing documentation

What’s methodology?– A methodology describes the approach and

the steps used to do things in a particular field, for example the field of information technology

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

Standard documentation process

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

The standard documentation process has a

number of steps

7 . U p d a te

6 . D is trib u te

5 . P rod u ce

4 . Tes t

3 . R eview

2 .D ra ft

1 . P lan

The standard documentation

process

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

The standard documentation process

Let’s look at the steps in detail:

1. Planning - Investigate

Firstly, investigate the problem – what exactly is it that you need?Eg.– What is the purpose of

the document?– Who is 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 – e.g. from an

older version

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. Planning – Designing the documentationElements of design for on-screen information


Factors that contribute to the appearance of on-screen documentation are:– Proportion– Orientation– Clarity and consistency– Colour and contrast


Proportion– Visual hierarchy of a page

on the screen.– Headings, logos and links

must be obvious to users on a company website

– Other information that company does not want to emphasise e.g. cost could be in a smaller font

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”

– The proportions or relative sizing of fonts and graphics, affect the visual hierarchy of the screen.

– Positioning of particular page elements e.g. white space around the objects, the formatting of fonts and the use of animation also affect the visual hierarchy of the screen.


Orientation– Orientation of objects on

screen such as logos , headings…

– Alignment of text (Left justify the bulk of text but what about headings I navigation bar?)

– The size and shape of the user documentation

– Can it be maximised to full screen

– Word wrap a good feature to have if size is changed.


Clarity– How clearly the information on

a screen is presented– No overcrowding (use plenty of

white space)– Font styles ( a sans serif font

when using on-line documentation such as Arial)

– Font sizes (10-12 point for bulk of text)

– Resolution of graphics

Consistency– Use of similar, repeated or

predictable features on a screen so navigation can be made easier.

– Using similarbackgounds pages or a template

– Elements that can be used consistently are-logos, font styles, numbering or bullet points style, search fields and navigation icons

– Colour scheme– Consistent use of font style and

sizes


Colour– Should make the information clear,

readable and attractive– Enhance important features and ensure

ease of navigation– Use same colour scheme on all pagesSome Conventions are:– Most readable is black text on white

background– Avoid using red and green together(Blue and

brown together can also be a problem)– Limit the variety of colours (<=4)– Light or pastel colours best for background.– Blue for an unvisited link, changing to purple

when visited is the standard. If other colours are chosen be consistent.

Contrast– Visual difference between colour

or tone between items on screen (e.g. Never have yellow on a white bacground)

– The greater the contrast the more legible the writing

– Balance of text, graphic or white space attracts the eye

– Do not use have a solid text block. Use headings and /or pictures.

1. Planning – Designing the documentationOther factors that affect the quality of user Interfaces

– Usability• Navigation• Superfluous text and elements such as logo, buttons…• Avoid scrolling

– Accessibility• Use common words such as Help and Search• Clear and easy to follow instructions take into account your audience e.g. visually impaired…• Is the software readily available eg. Adobe acrobat for PDF, Flash for animations

– Functionality• Do all features work- buttons, links, graphic format• Is download time < 5 sec

– Presentation• Proportion, orientation, clarity and consistency and colour and contrast

1. Planning – Designing the documentationEffective Information Architecture for on-screen information products

– This refers to the way the information is structured and the ways it can be navigated by the user

• Use of search fields• Clicking on words, icons• Menu or navigation bar• Hyperlinks

– Site maps or storyboards should be used to carefully plan the structure

– Must be logical for user

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 clearlyUse simple words – for example, use ‘carry out’ rather than ‘implement’, or ‘find out’ rather than ‘locate’

2. Drafting – writing style (cont)

Keep paragraphs and sentences shortMake 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 pageUse your spelling

and grammar checkers!

2. Drafting – writing style continued

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

2. Drafting – what to include

Use the steps of the information processing cycle (modified) to help you out. Remember it is about how you use the software not how you created the software. Some appropriate headings are:

– Introduction (Home page)– Opening a document– Inputting data– Validating and editing Data– Printing data (or producing other output)– Saving data– Deleting unwanted data– Closing the document– Exiting the software

3. Reviewing

Once a draft of the documentation has been done, it should be reviewed (checked) by another personThe 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

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 documentationIf 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 documentationFor larger organisations or complex documentation, professional printing and binding may be necessaryIn 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-basedThe process of developing documentation should follow a process that includes planning, drafting and reviewingWhen writing user documentation, certain conventions with regard to style and typographic standards should be adhered to

Summary (continued)

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

Examples of on-line user documentation

Explore some examples of on-line user documentation and make some notes of features you could use when creating your own. Make sure that you take into account all the factors to produce effective user documentation so you can produce a high quality end product.Examples of on-line user documentationhttp://audacity.sourceforge.net/help/documentation http://office.microsoft.com/en-us/sharepointtechnology/results.aspx?qu=word&av=WSU120 http://livedocs.adobe.com/flash/9.0/UsingFlash/

Check out the Help for microsoft office software

user documentation created by vitta modified by d.lupone using text book potts et.al (2007)

Documents