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