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

  • Application Security Tools - OWASP

    Application Security Tools - OWASP

    Code Review / Pen Test performed only by 3rd parties ($) A corporate world example The OWASP Solution: Awareness training for developers (OWASP Top 10 / Webscarab / Webgoat) Help developers guard against security design and implementation flaws (OWASP ESAPI)...
  • Life After Implementation: Ensuring 24 x 7 Availability

    Life After Implementation: Ensuring 24 x 7 Availability

    Not all machines for a service in the same rack, on the same plug strip, on the same circuit, in the same electrical panel, etc. Same for network, not on the same subnet, same switch, etc. Test Gear Test environment...
  • Identity Theft Seminar Power Point session

    Identity Theft Seminar Power Point session

    Credit performs skip tracing, issues refusal of service, notes premise and contacts customer for payment. Customer Service . determines if this is same party. Applies appropriate deposit rules. SSN and/or DL provided is same as on an existing account. SSN...
  • Positioning, Re-Branding & the Lions Club Marvin Ryder

    Positioning, Re-Branding & the Lions Club Marvin Ryder

    Marvin Ryder. Assistant Professor, Marketing & Entrepreneurship. DeGroote School of Business. McMaster University . Let's Start with Some Consumer Behaviour. Brand Awareness! A Little Exercise - Write down all of the luxury car manufacturer names that come to your mind!
  • Climate and Weather - mrdgeography

    Climate and Weather - mrdgeography

    As you go up in elevation the temperature becomes colder because the atmosphere is thinner. Areas with very high elevations can have vegetation similar to the arctic. Climate Zones Climate zones are classified by temperature and precipitation. Climate Zones Low...
  • Data Warehouses

    Data Warehouses

    * Is the Lost Profits Limitation Clause Part of the Contract? Is there an Acceptance? ... Offeror Objects * Material Alteration Surprise or Hardship Standard Clauses that deny implied warranties Clauses that require arbitration Clauses that limit remedies * May...
  • Parkin-Bade Chapter 34

    Parkin-Bade Chapter 34

    Core inflation rate provides a better measure of the underlying inflation trend and a better prediction of future CPI inflation. Monetary Policy Objectives and Framework "Maximum Employment" Goal Price stabilization is the primary goal but the Fed pays attention to...
  • Schaffer and Emerson plenary

    Schaffer and Emerson plenary

    Which of Schaffer's stages is the infant at and why? Jane seemed interested when shown the red balloon, her teddy or her older sister. She seemed quite excited when her dad came back home from work but she also seemed...