Presentation on theme: "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."— Presentation transcript:
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 Usage caseHardware exampleSoftware example Near none – plug in and forgetPC speakersAnti-virus Basic – even a kid could work itVacuum cleaner, lamp Notepad 1-time – do and learnWashing machineKeyboard 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 Every one and no one. Usage is key Have to be aware of target audience
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: –
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: –
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: “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:
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 – 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 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:the steps to task completion – 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: –
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: Manual suggestshttp://www.wikihow.com/Create-a-User- Manual – 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 ) ItemHeading/SectionDescription 1System overviewA short description of the capabilities of the software (1 paragraph) 2Hardware / Software requirements Briefly outline the minimum hardware and software requirements for the software to function properly. 3Initial setupDescribe the procedure of the software installation. Use a step-by-step approach (use bullets and numbering). 4Menu optionsExplain the functionality of the menu. Show the menu screenshots. 5ProceduresFor each function of the software explain step-by-step how a user can successfully complete it. 6TroubleshootingMake a list of some common problems the user can face with the software. Outline the solution to each problem. 7Backing up the systemExplain step-by-step how a back-up of the software can be done. 8Restoring from backupExplain 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