Writing User Guide

1
Writing User Guide

• CSC207 Software Design

2
Writing in CS

• Email/Newsgroup/Forum/Blog
• Code Comments
• Software User Guide
• Presentations
• Project Plans
• Software Requirements Specifications (SRS)
• Test Plans
• Research Papers
• Posters

3
Writing for the Project

• At the end of project you should have a complete
  program, including
• Javadoc
• Testing
• User guide

4
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?

5
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

6
Components of a UG
7
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

8
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!

9
References

• User Guide Tutorial
• http//www.klariti.com/technical-writing/User-Guid
  es-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.ht
  ml
• How to Publish a Great User Manual
• http//www.asktog.com/columns/017ManualWriting.htm
  l

10
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.

11
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?