Presentation on theme: "A guide into writing user guides"— Presentation transcript:
1A guide into writing user guides User ManualA guide into writing user guides
2ContentsWhat is the user manual, who uses it (and when), What do you expect to see in a user manualUsing procedures to explain operation, writing proceduresUser manual structure, from setup to backup and restoreOther sources of information
3What 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.
4Who uses a user manual/guide Every one and no one. Usage is keyHave to be aware of target audienceUsage caseHardware exampleSoftware exampleNear none – plug in and forgetPC speakersAnti-virusBasic – even a kid could work itVacuum cleaner, lampNotepad1-time – do and learnWashing machineKeyboard shortcuts for functionalityOccasional configuration – need to setup form time to time1-4-all remote controlFind out specific functions of a gameEvery time – long-winded, detailed instructionsPutting together something from IKEADoing tax return online
5Expected contents According to the wikihow: Create a User Manual Include appropriate cover and title pagesPut references to related documents in the prefaceInclude a table of contents (if pages >10)I say above 5-7; depends on the contentsPut instructions/procedures and reference materials inside the bodyUse graphic images as needed to support a textFor difficult or complicated pointsSource:
6What to you expect to see in it, another site Five tips for writing a user manualThink like a userKnow your audience and write accordinglyUse active voiceNO: To make this chair a screwdriver and hammer are neededYES: You need a screwdriver and hammer to make this chairFocus on the readerNO: there are three options to perform this taskYES: you can choose one of three way to perform this taskWrite clear instructionsClarity is key and the primary role of a manualEstablish standardsUse established standard styles (LaTeX document class) and enhance them by inserting your own customization to help with the clarity of the documentSource:
7Using proceduresA 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 performedWhat are the immediate (on screen) viewable effectsSource:“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:
8Procedure 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”
9Writing a procedure It is not It is Rocket-science A technical report …difficultIt isSimple step-by-step guide to completing tasksAn explanatory document on how a user can work with the system…relatively easy
10Writing 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.
11How to write the user manual According to the wikihow: Write User ManualsKnow your productKnow the purpose for the user manualDo an audience analysisOrganize the manually logicallyInclude all necessary partsTOC, Glossary, Index, list of figures, appendicesSpeak to your audience in term they will understandProofread the manualGet the manual approvedSource:
12User manual structureThe structure of the user manual should be clear and follow a logical orderThe reader has to be guided from getting to know the system through to the getting to use the systemOn designing a readable user manualSource: suggestsChoose a few readable fontsGive some thought to the layoutConsider the type of binding for the user manualBuild a template document for your manual
13Structure (from G.Stylianou material) ItemHeading/SectionDescription1System overviewA short description of the capabilities of the software (1 paragraph)2Hardware / Software requirementsBriefly 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.
14User manual end summary A useful reference document to assist in the operation of a systemTechnical but at the same time not intended for technical readersSuggestions: print do not provide e-formBe clear, use procedures with clearly defined steps, be consistent and use structured formatting