Writing User Guide CSC207 Software Design Writing in

Writing User Guide CSC207  Software Design Writing in

Writing User Guide CSC207 Software Design Writing in CS Email/Newsgroup/Forum/Blog

Code Comments Software User Guide Presentations Project Plans Software Requirements Specifications (SRS) Test Plans Research Papers Posters Writing for the Project At the end of project you should have a complete program, including: Javadoc Testing

User guide User Guides Purpose is to allow a user to install, use and troubleshoot a piece of software Some questions to think of when writing a user guide: Who is your audience, who are your users? Are there different groups of users? What level of technical expertise do they have?

How much time will they invest in reading the UG? Where/how will they read the UG? Is this product an upgrade to an existing product? What tasks are the users typically going to perform with the software? Will different groups of users perform different tasks? User Guides There are many online resources to help See reference list Generally, UGs employ the following style elements: Headings and Lists: help user find information quickly Special Notices: warnings, cautions or alerts, to alert readers to

important points Instructional Design: task-oriented headings, tasks in numbered lists, chunking together related tasks Graphics: screenshots and pictures, before and after views Tables: present data in an easy-to-access form, good for look-up information like OS types or minimum system requirements Highlighting: can be useful if used consistently and sparingly Components of a UG Tips on Content Use direct commands to the user: Click this; and you, not the user

Explain the problem being solved: dont just include a detailed description of features, explain why a user might want them Present the concepts, not just the features: if users understand the underlying concept of the software, they will more easily understand the features Give them more: manuals cover the task domain, not just the

software Make it enjoyable to read (but keep it professional): Your Macs software is the result of an accidental collaboration among hundreds of programmers. [David Pogues introduction, in the Conflict Catcher 8 manual] Tips on the Writing Process Ensure the writers are part of the software design team Write the user manual while you are developing the software Dont try and write it quickly before a release deadline

Make sure the writers have access to the software, have used the software, and are using the software while they write Consider the needs of disabled users Low vision, colour blindness, loss of acuity Your boss cant see as well as you can! References User Guide Tutorial http://www.klariti.com/technical-writing/User-Guides-Tutorial.shtml

User Guide Wikipedia http://en.wikipedia.org/wiki/User_guide Tips for Writing User Manuals (very slow if there) http://www.userfocus.co.uk/articles/usermanuals.html How to Publish a Great User Manual http://www.asktog.com/columns/017ManualWriting.html

Activity 1: Writing a User Guide We will write a partial short User Guide for a simple application. Try to decide which components are or are not necessary for your guide Come up with an outline. Max length: 2 pages (1 page double sided) Time: 10 minutes Try to describe one or two example features/functionality. Dont worry if you dont complete the guide. Activity 2: Critiquing a User Guide

Give your User Guide to someone else, and get someone elses User Guide. Spend 5 minutes making both positive and negative comments on the Guide. Is it missing important information? Are the instructions clear? Would they be understandable for a non-technical user?

Recently Viewed Presentations

  • Java, Java, Java - Computer Science

    Java, Java, Java - Computer Science

    Multiway Selection We can embed if-then-else clauses to create multiway selection structures. Note that this complicated structure has one entry and one exit. Selection Statement Examples The Dangling Else Problem Rule: An else clause matches the closest previous unmatched if...
  • LBSC 690: Week 5 - Metadata, Structured Documents, and XML

    LBSC 690: Week 5 - Metadata, Structured Documents, and XML

    LBSC 690: Week 5 Metadata, Structured Documents, and XML Jimmy Lin College of Information Studies University of Maryland Monday, February 26, 2006
  • Using Music and Rhythm in the everyday teaching of English ...

    Using Music and Rhythm in the everyday teaching of English ...

    of English Language. in Malaysian Schools. Using Music and Rhythm. So, where are we going today? ... Using Chants and Rhymes. Nursery Rhymes. Ready-made chants. Making your own chants: 3. Using Simple Songs ... Using Music and Rhythm in the...
  • An analysis of penalty biases called in the NHL during the ...

    An analysis of penalty biases called in the NHL during the ...

    With this data, The Predators finished with 20 more points in the regular season finishing in 10th place overall (7ths place in the western conference clinching them a playoff spot with 100pts, where whereas Tampa with only 80 points finished...
  • U.S. Coral Triangle Initiative Support Program US CTI

    U.S. Coral Triangle Initiative Support Program US CTI

    U.S. Coral Triangle Initiative Support Program US CTI Support Program Overview APEC LRFFT MEETING Sanur, Bali, Indonesia March 2, 2011 Maurice Knight
  • Land, Conflict & Characters  Symbolism  Motifs  Juxtaposition The

    Land, Conflict & Characters Symbolism Motifs Juxtaposition The

    The Secret River. READ: (p. 100) "They call this Broken Bay, Blackwood said.River comes in yonder. Best hidden river in the world, Blackwood said with satisfaction.". Thornhill strained to find that secret river." "As the boat glided along on the...
  • AIP OR Preceptorship - Megan Hellrung UEXCEL Portfolio

    AIP OR Preceptorship - Megan Hellrung UEXCEL Portfolio

    Background: preceptorship in aip or. Preceptorship is defined in current professional practice literature as a specialized one-on-one relationship where on-site clinical experience is facilitated by an experienced staff member assuming the role of clinical instructor in order to bridge the...
  • Chemistry Analysis What is this? Three central goals

    Chemistry Analysis What is this? Three central goals

    Linkage isomers An artist's wheel Splitting of d-orbital energies by an octahedral field of ligands D is the splitting energy The effect of ligand on splitting energy The spectrochemical series For a given ligand, the color depends on the oxidation...