A guide into writing user guides User Manual A guide into writing user guides

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

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.

Who uses a user manual/guide Every one and no one. Usage is key Have to be aware of target audience Usage case Hardware example Software example Near none – plug in and forget PC speakers Anti-virus Basic – even a kid could work it Vacuum cleaner, lamp Notepad 1-time – do and learn Washing machine Keyboard shortcuts for functionality Occasional configuration – need to setup form time to time 1-4-all remote control Find out specific functions of a game Every time – long-winded, detailed instructions Putting together something from IKEA Doing tax return online

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

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/

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

Procedure examples “How to configure TexMaker’s QuickBuild 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”

Writing a procedure It is not It is 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

Writing procedures http://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.

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

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

Structure (from G.Stylianou material) Item Heading/Section Description 1 System overview A short description of the capabilities of the software (1 paragraph) 2 Hardware / Software requirements Briefly outline the minimum hardware and software requirements for the software to function properly. 3 Initial setup Describe the procedure of the software installation. Use a step-by-step approach (use bullets and numbering). 4 Menu options Explain the functionality of the menu. Show the menu screenshots. 5 Procedures For each function of the software explain step-by-step how a user can successfully complete it. 6 Troubleshooting Make a list of some common problems the user can face with the software. Outline the solution to each problem. 7 Backing up the system Explain step-by-step how a back-up of the software can be done. 8 Restoring from backup Explain step-by-step how the backed-up software can be restored.

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