User Guide - Computing and Software
Contents
1. Spencer Smith amp Mark Lawford Software Quality Research Laboratory McMaster University Hamilton ON Canada January 21 2008 ORL Sere Qaley keser Latono Smith amp Lawford SQRL User Guide January 21 2008 1 36 Outline Q Motivation amp Overview Marking Guidlines Definitions 5 On Instructions Conclusions January 21 2008 ORL Sere Qasr 2 36 Smith amp Lawford SQRL User Guide Motivation amp Overview User s Guide Each team will produce a user guide describing the installation use troubleshooting etc for their product Examples Previous capstone projects are on WebCT e Manuals for any software product Informal document Know your audience e Assume the IBM judges are your audience e Assume little prior knowledge of the software or the application domain e Assume basic computer literacy IBM judges will use this so that they have a feel for your product in advance of the final demonstration day Preparing the user manual will help you think about usability ORL requirements ied Smith amp Lawford SQRL User Guide January 21 2008 3 36 Motivation amp Overview Marking Marking Scheme Spelling and grammar 15 Each mistake takes off 5 to a maximum of 15 First two mistakes are without penalty Style 10 Paragraph structure logical grouping of ideas Concisely expressed ideas not overly wordy Flow between paragrap2. 28 Vancourt Model AL 8 overhead projectors in rooms A4 and A32 are to be bolted to their projection tables b Why via a purpose statement IRL Sere Qaley keser Lator Smith amp Lawford SQRL User Guide January 21 2008 19 36 On Instructions Giving Instructions Continued a What via a summary statement The 28 Vancourt Model AL 8 overhead projectors in rooms A4 and A32 are to be bolted to their projection tables b Why via a purpose statement o to reduce the current high damage rate caused by projectors being accidentally knocked onto the floor IRL Sear Qaley keser Lator Smith amp Lawford SQRL User Guide January 21 2008 19 36 On Instructions What information is necessary before beginning via a short paragraph list for instance Example What information Before beginning you will need Sympatico User ID Access Password Sympatico email address How via step by step instructions Example How Turn off your Anti Virus and Firewall Software as this software will interfere with the installation process Place the Software e Setup CD in your computer s CD ROM drive Smith amp Lawford SQRL User Guide On Instructions Clear and Concise Instructions Before the trap is set it is a good idea to place a small piece of cheese on the bait pan If it is too small it may fall off and if it is too big it might not fit under the serrated edge so make
3. CR timer is broken You need to have your favourite show taped since you re going out but your CompEng roomie is hopeless he just can t remember how to use the VCR So you re going to have to leave him instructions on how to operate the video recorder ORL Sear Qaley keser Latona Smith amp Lawford SQRL User Guide January 21 2008 24 36 On Instructions Situation The VCR timer is broken You need to have your favourite show taped since you re going out but your CompEng roomie is hopeless he just can t remember how to use the VCR So you re going to have to leave him instructions on how to operate the video recorder The Wrong Way D00d Let s see if we can get it right this time I don t want to be watching Desparate Housewives like last time You need to put the video in the machine and then press the record button That s the small red one which is a little to the left of the play button which looks like a Smartie with an arrow on it you can t miss it The stop button is just below the play button I think Oh by the way don t forget to rewind the tape first and you ll need to change the channel too probably Smith amp Lawford SQRL On Instructions Example Bad and Good Instructions cont The Right Way Put the tape in the machine Press rewind and wait until the rewinding has finished Change the channel to 5 The record button is the red one in the top left corner Pre
4. a damage to Pacemaker board etc Cautions To tell the reader that care is needed such as quitting all open applications or recording sensitive data before proceeding to the next screen Notes To make general comments such as noting that the hot keys have been changed between versions of the software ORL Sere Qala Smith amp Lawford SQRL User Guide January 21 2008 32 36 On Instructions Use Consistent Typographic Conventions Warnings Courier font for text typed as input ALT h CTRL ENTER etc January 21 2008 ORL Sear Qaley keser Latono 33 36 Smith amp Lawford SQRL User Guide On Instructions Inspect Via an Operational Check Test for usability The final test for any technical instruction is the reader s ease in following it You will not be able to help the reader they will only have your instructions Give the draft instructions to someone with the skills typical of your audience and observe them Make notes Rewrite ambiguous steps ORL Sere Qalysrchaeraty Smith amp Lawford SQRL User Guide January 21 2008 34 36 Conclusions Conclusions Your User Manual is the one piece of documentation the majority of you customers will actually ever see Good manuals sell products e g VW New Beetle Subversion Its the one thing most of the judges will look at so put effort into it ORL Sere Qaley keser Lator Smith am
5. ar and easy to understand Give direct and simple commands directions Don t ORL Sere Qaley keser Latono Smith amp Lawford SQRL User Guide January 21 2008 23 36 On Instructions Do s and Don ts Do Write your instructions in the right order Make your writing clear and easy to understand Give direct and simple commands directions Don t Add some jokes to your instructions ORL Sere Qasr Smith amp Lawford SQRL User Guide January 21 2008 23 36 On Instructions Do s and Don ts Do Write your instructions in the right order Make your writing clear and easy to understand Give direct and simple commands directions Don t Add some jokes to your instructions Give a detailed description of the system e g what the video player looks like ORL Sere Qalyesarchlaeraty Smith amp Lawford SQRL User Guide January 21 2008 23 36 On Instructions Do s and Don ts Do Write your instructions in the right order Make your writing clear and easy to understand Give direct and simple commands directions Don t Add some jokes to your instructions Give a detailed description of the system e g what the video player looks like Show off your technical knowledge of the product ORL Sere Qala Smith amp Lawford SQRL User Guide January 21 2008 23 36 On Instructions Example Bad and Good Instructions The V
6. d SQRL User Guide January 21 2008 28 36 On Instructions Avoid Indefinite Words Avoid should could would might and may Select the data A plot should appear in the centre of the screen Select the data A plot will appear in the centre of the screen ORL Sere Qaley keser Latona Smith amp Lawford SQRL User Guide January 21 2008 29 36 On Instructions Tell the Reader What to Expect Press Enter to begin the backup process This process may take several hours to complete depending on the size of your files Type the name of the installation directory If this directory does not already exist it will be created ORL Sere Qaley keser Latona Smith amp Lawford SQRL User Guide January 21 2008 30 36 On Instructions Write Bite Size Steps One step per instruction e Potentially use sub steps to describe a complex step If required click Reset to Factory Defaults Click Reboot Ifthe Reset to Factory Defaults option was selected the systems responds with Click the Reset to Factory Defaults button to confirm or click Cancel to return to the System Reboot screen A status screen begins a 45 second countdown to ORL Sear Qasr Smith amp Lawford SQRL User Guide January 21 2008 31 36 On Instructions Insert Fail Safe Precautions Warnings To alert the readers to potential damage to firmware or erasure of dat
7. ement or goal shared by all program family members ORL Sere Qaley keser Latona Smith amp Lawford SQRL User Guide January 21 2008 12 36 Definitions Too Narrow Goal Goals capture at the highest level of abstraction the objectives of an Air Traffic Control system ORL Sere Qasr aerate Smith amp Lawford SQRL User Guide January 21 2008 13 36 Definitions Too Narrow Goal Goals capture at the highest level of abstraction the objectives of an Air Traffic Control system This is too narrow Better would be ORL Sere Qala Smith amp Lawford SQRL User Guide January 21 2008 13 36 Definitions Too Narrow Goal Goals capture at the highest level of abstraction the objectives of an Air Traffic Control system This is too narrow Better would be Goal Goals capture at different levels of abstraction the various objectives the system under consideration should achieve Lamsweerde 2001 ORL Sere Qaley keser Latona Smith amp Lawford SQRL User Guide January 21 2008 13 36 Definitions Too Technical Program Family A set of sequences of operations that can be performed by a Turing complete system where these sequences can be analyzed and designed together starting from the initial stages of the software development life cycle ORL Sere Qaley keser Latona Smith amp Lawford SQRL User Guide January 21 2008 14 36 Definitions Too Technical P
8. ford SQRL User Guide January 21 2008 16 36 Definitions Definition Using Examples Element A domain can be discretized into smaller usually simpler shapes called elements The typical shapes for elements in 1D is a line in 2D is a triangle or a quadrilateral and in 3D a tetrahedron or a hexahedron Elements are also called cells ORL Sere Qasr aerate Smith amp Lawford SQRL User Guide January 21 2008 17 36 On Instructions Giving Instructions Chapter 9 of VanAlstyne 2005 Chapter 7 Blicq 1987 Define your audience Level of technical knowledge e Familiarity with application domain Start with a plan a What has to be done b Why it has to be done c What information is needed d How the work is to be done January 21 2008 ORL Sear Qasr aerate 18 36 Smith amp Lawford SQRL User Guide On Instructions Giving Instructions Continued a What via a summary statement ORL Sere Qaley keser Lator Smith amp Lawford SQRL User Guide January 21 2008 19 36 On Instructions Giving Instructions Continued a What via a summary statement The 28 Vancourt Model AL 8 overhead projectors in rooms A4 and A32 are to be bolted to their projection tables ORL Sere Qaley keser Lator Smith amp Lawford SQRL User Guide January 21 2008 19 36 On Instructions Giving Instructions Continued a What via a summary statement The
9. hs and sections Appropriate pointers in the document to help someone navigate it etc Overall opinion of content 20 Can the instructions be followed just from the manual Is the manual easy to read Is the manual enjoyable to read RI Sere Qaley keser Latona Smith amp Lawford SQRL User Guide January 21 2008 4 36 Motivation amp Overview Marking User Manual Marking Scheme Contd Overall opinion of content continued Demonstrate that you have thought about the software Show originality and creativity Report components and content 55 e Components such as Installation Simple tasks Complex tasks Troubleshooting Frequently asked questions Etc e Necessary background information on application domain ORL Sere Qasr Smith amp Lawford SQRL User Guide January 21 2008 5 36 Motivation amp Overview Marking User Manual Marking Scheme Cont d Report components and content Continued Will inspect with specific tasks in mind such as Install Open Save Close etc a file Starting up a session Communicate with the Pacemaker board Programming and monitoring a Pacemaker board Appendices if necessary Reference list Index if necessary Glossary if necessary ORL Sere Qasr aerate Smith amp Lawford SQRL User Guide January 21 2008 6 36 Motivation amp Overview IVETE Tare Evaluation of User s Guide Expect betwee
10. index RL Sere Qaley keser Latona Smith amp Lawford SQRL User Guide January 21 2008 9 36 Definitions Defining Terms Chapter 7 of VanAlstyne 2005 Know your audience Methods for definition e Parenthetical However you only need the version with a graphical user interface on the machine where you re actually going to display the interface the client machine Unision Manual e Brief phrase Subversion is a centralized system for sharing information At its core is a repository which is a central store of data Svn Manual Sentences Extended definitions ORL Sere Qala Smith amp Lawford SQRL User Guide January 21 2008 10 36 Definitions DEON ae UEO Too technical Too broad Too narrow Circular ORL Sere Qaley keser Lator Smith amp Lawford SQRL User Guide January 21 2008 11 36 Definitions Too Broad Circular Commonality Something two things have in common ORL Sere Qala Smith amp Lawford SQRL User Guide January 21 2008 12 36 Definitions Too Broad Circular Commonality Something two things have in common This is too broad circular Better would be ORL Sere Qaley keser Lator Smith amp Lawford SQRL User Guide January 21 2008 12 36 Definitions Too Broad Circular Commonality Something two things have in common This is too broad circular Better would be Commonality A requir
11. n 20 to 30 pages No page limit double space e Pictures and figures will be necessary Provide background information step by step installation step by step usage troubleshooting etc Consider this document to be a promotional tool emphasize what is best about your system A checklist is a good idea for writing the document but it does not need to be included WAL Sere Qala Smith amp Lawford SQRL User Guide January 21 2008 7 36 Motivation amp Overview Guidlines User Manual Guidelines Page should be on each page Break the text into sections e Text should usually appear between all section headings If a section has subsections the number of subsections should be greater than one Citations for ideas and for direct quotes in line for short quotations and indent and single space for long quotations User guide should be as self contained as possible ORL Sere Qaley keser Latona Smith amp Lawford SQRL User Guide January 21 2008 8 36 Motivation amp Overview Guidlines User Guide Content Details Title page Legal and copyright information Safety and precaution pages precautions with the pacemaker boards and with data integrity Table of contents List of tables List of figures Precise definitions Step by step instructions Maintenance and troubleshooting information Frequently asked questions Warranty information Possibly a glossary and an
12. p Lawford SQRL User Guide January 21 2008 35 36 Appendix References For Further Reading ll Ron Blicq Technically Write Prentice Hall 1987 fa Axel van Lamsweerde Goal oriented requirements engineering a guided tour In Proceedings of the 5th IEEE International Symposium on Requirements Engineering pages 249 263 IEEE IEEE Computer Society Washington DC USA August 2001 Judith S VanAlstyne Professional and Technical Writing Strategies Pearson Prentice Hall Upper Saddle River New Jersey sixth edition 2005 RI Sere Qaley keser Latona Smith amp Lawford SQRL User Guide January 21 2008 36 36
13. rogram Family A set of sequences of operations that can be performed by a Turing complete system where these sequences can be analyzed and designed together starting from the initial stages of the software development life cycle Too much technical detail Better would be ORL Sere Qaley keser Latona Smith amp Lawford SQRL User Guide January 21 2008 14 36 Definitions Too Technical Program Family A set of sequences of operations that can be performed by a Turing complete system where these sequences can be analyzed and designed together starting from the initial stages of the software development life cycle Too much technical detail Better would be Program Family A set of programs that are analyzed and designed together starting from the initial stages of the software development life cycle IRL Sere Qaley keser Latona Smith amp Lawford SQRL User Guide January 21 2008 14 36 Definitions Techniques for Definition Examples Description Synonym Contrast Negation Comparison Analogy Graphics IRL Sear Qaley keser Lator Smith amp Lawford SQRL User Guide January 21 2008 15 36 Definitions Definition Using a Synonym Program Family A set of programs that are analyzed and designed together starting from the initial stages of the software development life cycle Also known as a software product line ORL Setar Qaley keser Latona Smith amp Law
14. ss it Check the recording light is on Press stop when the programme has finished IRL Sere Qasr Smith amp Lawford SQRL User Guide January 21 2008 25 36 On Instructions Give your Reader Confidence Write in the imperative mood Start each step with a strong verb usually In some cases the start will be an introductory clause followed by a strong verb Make the instructions commands Instructions tell the user to do something Examples Ignite the mixture Mount the external hard drive Create and display the report Choose the OK button RI Sear Qaley keser Latono Smith amp Lawford SQRL User Guide January 21 2008 26 36 On Instructions Imperative Mood Which of the following are in the imperative mood Disengage the gear then start the engine The gear should be disengaged before starting the engine Before connecting the meter to the power source set all the switches to zero ORL Sere Qasr Smith amp Lawford SQRL User Guide January 21 2008 27 36 On Instructions Avoid Ambiguity Enter an appropriate password e Enter a password with between 6 and 10 characters where at least one character has to be nonalphabetic Turn on the computer e Depress the ON OFF key to the ON position Allow the glue to dry adequately Allow the glue to dry for six hours ORL Sere Qaley keser Latono Smith amp Lawfor
15. sure you get the right size Before setting the trap wedge an 8 mm cube of cheese firmly under the serrated edge of the bait pan ORL Sere Qasr Smith amp Lawford SQRL User Guide January 21 2008 21 36 On Instructions Clear and Concise Instructions Cut a 0 62 m length of 10 gauge wire and strip 20 mm of insulation from each end Solder one end of the wire to terminal 7 and the other end to pin 49 ORL Sere Qala Smith amp Lawford SQRL User Guide January 21 2008 22 36 On Instructions Do s and Don ts Do Sere Qaley keser Latono Smith amp Lawford SQRL User Guide January 21 2008 23 36 On Instructions Do s and Don ts Do Write your instructions in the right order ORL Sere Qasr Smith amp Lawford SQRL User Guide January 21 2008 23 36 On Instructions Do s and Don ts Do Write your instructions in the right order Make your writing clear and easy to understand ORL Sere Qasr Smith amp Lawford SQRL User Guide January 21 2008 23 36 On Instructions Do s and Don ts Do Write your instructions in the right order Make your writing clear and easy to understand Give direct and simple commands directions ORL Sere Qala Smith amp Lawford SQRL User Guide January 21 2008 23 36 On Instructions Do s and Don ts Do e Write your instructions in the right order Make your writing cle
Download Pdf Manuals
Related Search