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 cards Comprehensive user manuals Reference guides Brochures

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

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 documentation Elements 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 documentation Elements 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 documentation Elements 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 documentation Elements 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 documentation Elements 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 pages Some 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 documentation Other 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 documentation Effective 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 clearly Use 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 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. 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 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 The drafting, reviewing, re-drafting, reviewing, process may continue through two or more redrafts Is the draft correct, complete and clear? Draft documentationReview 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

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 documentation Check out the Help for microsoft office software