User Manual

1. User Manual A guide into writing user guides

2. Contents • What is the user manual, who uses it (and when), What do you expect to see in a user manual • Using procedures to explain operation, writing procedures • User manual structure, from setup to backup and restore • Other sources of information

3. What is a user manual/guide •  It is the useless piece of paper that comes with anything you buy and usually ends up in the trash or (best case) in a bottom drawer to the right of the kitchen sink  • Keep it • “we might need to return the item” • “sometimes these need setting up, we’ll refer to it” • “it includes troubleshooting when it’s not working” • An easy to use, read and understand document that can assist any user to realize how to operate a piece of software or hardware.

4. Who uses a user manual/guide • Every one and no one. Usage is key • Have to be aware of target audience

5. Expected contents • According to the wikihow: Create a User Manual • Include appropriate cover and title pages • Put references to related documents in the preface • Include a table of contents (if pages >10) • I say above 5-7; depends on the contents • Put instructions/procedures and reference materials inside the body • Use graphic images as needed to support a text • For difficult or complicated points • Source: • http://www.wikihow.com/Create-a-User-Manual

6. What to you expect to see in it, another site • Five tips for writing a user manual • Think like a user • Know your audience and write accordingly • Use active voice • NO: To make this chair a screwdriver and hammer are needed • YES: You need a screwdriver and hammer to make this chair • Focus on the reader • NO: there are three options to perform this task • YES: you can choose one of three way to perform this task • Write clear instructions • Clarity is key and the primary role of a manual • Establish standards • Use established standard styles (LaTeX document class) and enhance them by inserting your own customization to help with the clarity of the document • Source: • http://online-learning.com/blog/tips-writing-user-manual/

7. Using procedures • A procedure (AKA instruction, task) assists the user in performing a specific operation. These may include (and are not limited to): • When, why and how a task is performed • What are the immediate (on screen) viewable effects • Source: • http://www.klariti.com/technical-writing/User-Guides-Tutorial.shtml • “Procedures should be written in a consistent structure throughout the instruction section of the manual. Begin with an overview of the task, then describe what the user has to do and what result he or she should see. Steps should be numbered and begin with action verbs, as the steps in each section of this article are written” • Source: http://www.wikihow.com/Create-a-User-Manual

8. Procedure examples • “How to configure TexMaker’sQuickBuild to use a specific library (e.g. PdfLatex) to generate LaTeX documents.” • “How to insert a table in Microsoft Word” • “How to use Headings defined in Microsoft Word in order to create table of content entries automatically” • “How to download and install Ubuntu on the Intel Platform”

9. Writing a procedure • It is not • Rocket-science • A technical report • …difficult • It is • Simple step-by-step guide to completing tasks • An explanatory document on how a user can work with the system • …relatively easy

10. Writing procedureshttp://www.userfocus.co.uk/articles/uermanuals/html • Provide step-by-step sequences in the correct order. • Follow the timing and sequencing of the actual operations . • Provide visual stepping stones (e.g. Step 1, Step 2 etc.) • Avoid lengthy paragraphs. • Use everyday words and terms: avoid jargon. • Explain what a function or feature is for as well as "How to" instructions. • Check that the instructions match the actual product. • Explain symbols, icons and codes early. • Avoid creating dead-ends. • Avoid patronising the user. • Do not assume the user has prior experience or product knowledge. • Usability test the instructions alongside the product using naive users. • Write in the present tense and the active voice. • Write the steps to task completion while doing the actual task on a real product. Have an independent user then follow the steps (literally) with the product and check that: • It is easy to work through the task from start to finish. • It is easy to break out of task and get back in. • It is easy to jump into the user manual half way through a task.

11. How to write the user manual • According to the wikihow: Write User Manuals • Know your product • Know the purpose for the user manual • Do an audience analysis • Organize the manually logically • Include all necessary parts • TOC, Glossary, Index, list of figures, appendices • Speak to your audience in term they will understand • Proofread the manual • Get the manual approved • Source: • http://www.wikihow.com/Write-User-Manuals

12. User manual structure • The structure of the user manual should be clear and follow a logical order • The reader has to be guided from getting to know the system through to the getting to use the system • On designing a readable user manual • Source: http://www.wikihow.com/Create-a-User-Manual suggests • Choose a few readable fonts • Give some thought to the layout • Consider the type of binding for the user manual • Build a template document for your manual

13. Structure (from G.Stylianou material)

14. User manual end summary • A useful reference document to assist in the operation of a system • Technical but at the same time not intended for technical readers • Suggestions: print do not provide e-form • Be clear, use procedures with clearly defined steps, be consistent and use structured formatting