4. Create client user documentation and 5. Obtain endorsement/sign-off

1
4. Create client user documentationand 5.
Obtain endorsement/sign-off
2
User Documentation

• This unit describes User Documentation in detail.
  User documentation is one form of support for
  users, and the requirements for documentation are
  many and varied. The different types of user
  documentation and their purpose are examined
  here.

3
Types of user documentation

• In unit 1 you learnt that user documentation can
  be printed or online, and assists people (that
  is, users) to use a computer system. You looked
  at different types of user documentation
  (instruction, training, policy and procedures).
• User documentation can take various forms,
  depending on the needs of the audience and the
  scope of the project. The forms of documentation
  include

4

• users reference guides
• quick reference cards
• handbooks
• keyboard templates
• wall charts
• training manuals
• computer-managed learning
• computer-based training
• tutorials
• wizards
• cue cards
• frequently asked questions
• glossaries
• troubleshooting information
• navigation aids
• context-sensitive help
• access to documentation on the Internet
• intranet documentation.

5
Users Reference guide

• Containing comprehensive information about the
  software. There purpose is to
• enable users to learn how to use the software,
• provide accurate reference info,
• supply step-by-step details about how to complete
  tasks using the software,
• help users understand their role in the process
• explain why, as well as how a process is
  performed. It can be structured as task-based
  procedures or as menu-driven screen descriptions.

6
Quick Reference cards

• Day to Day prompts of how to complete tasks.
  There purpose is to
• list key functions
• act as a memory jogger about what to do next
• summarise information
• match the needs and level of expertise of
  specific users

7
Handbooks

• Handbooks are scaled down documents that provide
  basic information to business partners or outside
  contractors who may need to supply or use data.
  Can also be written for software users who do not
  need the full details contained in the users
  reference manual.
• Purpose is to
• summarise key functions used by target audience
• provide step-by-step instructions
• help users to use the software confidently and
  accurately.

8
Keyboard templates

• Some applications use the function keys on a
  standard keyboard to perform certain tasks. For
  example, pressing the Fl key initiates the Help
  function. Keyboard templates are cards that are
  sized to fit above the function keys on a
  standard keyboard. They help the user remember
  which keys to press for different functions.

9
Wall charts

• Wall charts are often useful for depicting the
  stages in a process. Thus, a group of users can
  see at a glance what should be done next, or who
  to notify when a process is completed. Wall
  charts are quick and easy to prepare and are
  popular with users, but are often forgotten when
  considering user documentation requirements.

10
Training manuals

• Training manuals are usually only prepared when
  there is an organised training program. A
  training manual has a different role from that of
  a users reference guide, and requires a
  different approach. The purpose of a training
  manual is to
• build user acceptance of the software. Most
  people have an automatic reluctance to use or
  learn something new, and the training manual must
  make the transition easy and painless.

11

• provide users with customised working examples of
  how to perform a task using the software. This
  means that different training manuals must be
  prepared for each user group. The examples used
  for training data-entry clerks will be different
  from the examples used for training sales staff
• lead the audience through the users reference
  guide, so that they have some familiarity with it
  and are therefore more likely to accept it and
  use it
• provide a structure for trainers to follow so
  that the training delivery is consistent in
  content and approach
• give realistic activities so that users can
  practise in a controlled environment.

12
Computer-managed learning (CML)

• Computer-managed learning (CML) is concerned with
  the online management of learning. In CML the
  computer is used to plan, organise, control,
  evaluate and assess what the student learns.
  Computer-managed learning can be used to select a
  study path for the student based on a combination
  of student performance and choice of options.

13
Computer-based training (CBT)

• Computer-based training (CBT) is also referred to
  as computer-assisted learning (CAL). It is
  concerned with presenting material and then
  testing the student with drills and practice. It
  is perhaps best described as an online tutorial
  that includes testing.

14
Tutorials

• Online tutorials come with many packages. They
  cannot be classified as CBT as they do not, in
  the main, assess the performance of the student.

15
Wizards

• Many software programs have assistants or wizards
  to help the user achieve particular tasks by
  answering a series of questions or prompts
  regarding the operation they want to accomplish.
  For example, you may create a database in Access
  2002 using the wizards provided.

16
Frequently asked questions (FAQ)

• At the testing stages of a new product, different
  people often ask similar questions. To avoid
  technical support hotlines being asked the same
  question repeatedly, a section in the
  documentation may be devoted to frequently asked
  questions (FAQ).

17
Glossaries

• A feature of many Help systems is a glossary,
  where all the terminology relevant to the
  application is explained. A glossary can be
  helpful if a user (and their company) has a
  particular way of referring to things, or a
  package uses jargon.

18
Troubleshooting information

• This is where people turn to when the application
  is not functioning as it should or as the user
  expects it to. During the testing stage of
  software development, all the problems testers
  have discovered with the software can be analysed
  and described in the troubleshooting section.

19
Navigation aids

• For some applications the online documentation is
  vast, and so being able to navigate around the
  documentation easily is very important. Helpful
  navigation aids include
• contents menus
• indexes with AZ buttons to go straight to the
  area of interest
• browse sequences, in which related topics are
  grouped together so they can be skimmed using
  browse buttons (browsers)
• search facilities to enable the user to find
  topics relating to a particular key word.

20
Context-sensitive help

• What the user wants is relevant help. Ideally,
  they should be able to find it immediately rather
  than having to search for it.

Documentation on the Internet

• Help can often be found on the Internet in the
  form of information about a product, answers to
  FAQ and so on. Websites can also provide fixes
  and upgrades for users to download. This is a
  cheap and effective means of distributing
  software.

21
Intranet documentation

• Many organisations are converting all their
  text-based files into HTML documents. This has
  the enormous advantage that anyone can view these
  documents. Prior to using HTML, if someone wanted
  to view a document written in PDF format, for
  example, they needed a copy of Acrobat Reader to
  view the document.

Activity 3.1
22
Purpose of User Documentation

• In unit 1 you learnt that the purpose of user
  documentation is to support people who use a
  computer system, both hardware and software.
  Users require documentation in three ways for
  training, to understand the computer system, and
  as a reference. These uses may be covered by just
  one item or by a set of specialised manuals, both
  written and online.

23
Understanding

• Users generally like to know something about a
  computer system before they use it. They may need
  this information to select or evaluate a product.
  An application also requires promotion to make
  potential users aware of its existence.

24
Training

• Most users require some form of training. Formal
  training sessions with a human trainer can be
  very effective, but often computer users do not
  attend them. Instead, lacking time and facilities
  for adequate training, many make do with a
  trial-and-error approach.
• User documentation for training can come in any
  form of media. User manuals may include a
  tutorial section that takes the user through the
  steps of a common task or set of tasks.

25
Reference

• Users need to be able to refer to material that
  is specific and detailed enough to assist them
  with their tasks. This reference facility is
  vital. A function in an application may require a
  particular syntax or sequence of steps

Activity 3.2
26
Developing user documentation

• In unit 1, we looked at the standard
  documentation process, which consists of the
  following steps
• Planning.
• Drafting.
• Reviewing.
• Testing.
• Producing.
• Distributing.
• Updating.

27

• Before starting to write documentation, you
  should plan what to do. Planning now can help you
  provide documentation that satisfies the prime
  objective of supporting the user. Planning
  involves
• investigating the problem
• defining the target audience their skill level
  and needs
• determining documentation requirements
• designing the documentation
• selecting suitable methods.

28
Investigating the problem

• When deciding what documentation is required for
  a particular computer system, you need to find
  out more about the computer system to be
  documented. A number of questions need to be
  asked, such as
• Is the package a simple program, or is it likely
  to require a large amount of online assistance
  for a variety of users at different skill levels?
• What operating system (s) is the software
  designed for?
• I Is the product an upgrade of a previous
  version? If so, perhaps a Whats new section
  may be required.

29

• The purpose of the documentation needs to be
  clearly stated. For example, for a sales support
  application it may be
• To enable novice users to operate the three major
  functions of the application by following a
  step-by-step tutorial.
• To allow the average user to complete the
  tutorial in twenty minutes.
• To enable the user to
• add clients
• search for and retrieve/modify client details.

30
Defining the target audience

• The intended audience or user must be identified,
  and their background and any other factors
  relevant to their use of the application stated.
  For example, language, culture, attitudes and
  work environment may be important. Are users
  familiar with the job that the software was
  designed to assist with?

31
Novice

• A novice is a user who has not had any exposure
  to the application but must be able to become
  proficient in using it.

Intermediate

• The intermediate user has had initial training.
  They have used the application to a degree where
  they are familiar with the major functions and
  can perform most of their duties with that
  application.

32
Expert

• Expert users have had advanced training or have
  used the application for an extended period. They
  have extensive knowledge of the application and
  are proficient users. A reference card would be
  suitable.

Casual

• Casual users use the application for specific
  functions on an irregular or infrequent basis.
  They only need to know a limited range of
  functions and should be able to use the
  application efficiently after lengthy absences.

33
Determining documentation requirements

• Having decided on the nature of the documentation
  required, you now need to design it. If you
  attempt to create the documentation without
  designing it properly first, a lot of work may
  need to be redone later.

34

• Your design should specify
• standards and styles for text and graphics
• graphics how they will fit into the page layout
• topics which will be covered or addressed and
  at what level. This should be consistent with
  user needs and characteristics.
• style and tone these help determine the
  impression the documentation will make on the
  user. This should be compatible with such things
  as the language, culture and attitudes of the
  user.
• typographic standards (for example, font size and
  type) these will influence the readers ability
  to understand the documentation.

35

• Designing documentation is a three-stage process
• designing the overall structure of the help
  topics, also referred to as pages or screens
• designing the links that enable navigation around
  the system
• designing the contents of each screen.

36
Selecting suitable tools to develop the
documentation

• Various tools are available for developing
  documentation. For printed documentation, they
  include word processing, desktop publishing,
  drawing and scanning software. Tools for
  producing online documentation include soft ware
  packages that generate Windows Help files (such
  as HDK, Help developers Kit), Internet or
  intranet documents (such as Microsofts Front
  Page) and online tutorials (such as Authorware).

37
Drafting

• Drafting is the actual writing (or authoring) of
  the documentation, and is usually the most
  time-consuming task. Several writing techniques
  can be used to make the documentation
  understandable to the user, and these are
  discussed in this section.
• At the end of each day you should always back up
  your files. Every writer knows the frustration of
  files being corrupted or damaged and not
  adequately backed up.

38
Reviewing

• After the document has been drafted, various
  aspects including content, grammar and style
  should be checked. Someone other than the writer
  should do this, as the other person (or people)
  will see things that are not obvious to the
  writer. Professional publishers of documentation
  use several reviewers, including technical and
  language editors.

39

• Some of the things that are checked are
• Content
• Is the information correct? Is there any
  information omitted that should be in? Is there
  any information that is irrelevant and should be
  omitted?
• Grammar
• Is the documentation grammatically correct? Are
• there spelling errors?
• Standards
• Are organisational standards followed?
• Clarity
• Is the documentation clear and understandable to
  the reader?
• Interest
• Does the documentation hold the readers interest?

40
(No Transcript)
41
Writing style

• The style of writing is an important factor in
  determining the quality of documentation (both
  online and printed). The following features can
  influence how well the documentation is
  understood by the reader
• language
• word simplicity
• sentence and paragraph length
• spelling and grammar
• consistency
• active voice
• word emphasis.

42
Printed documentation

• Some criteria can be used to evaluate how
  effective the printed documentation is. Some of
  the criteria apply to all forms of documentation,
  and others apply specifically to printed
  documentation. Table 3.8 lists the evaluation
  criteria, with those specifically for printed
  documentation marked with an asterisk ()

43
Activity 3.5
44
Online documentation

• Criteria can also be used to evaluate the
  effectiveness of online documentation. Some apply
  to all forms of documentation and others
  specifically to online documentation. Table 3.9
  lists evaluation criteria, with those
  specifically for online documentation marked with
  an asterisk ().

45
Activity 3.6
46
Summary

• The three basic purposes of user documentation
  are understanding, training and reference.
• A general methodology has the following steps
• Planning.
• Drafting.
• Reviewing
• Testing
• Producing
• Distributing
• Updating.

47
4. Obtain endorsement/sign-off

• Developed documentation is reviewed by target
  audience. After documentation has been completed
  it needs to be tested by the target audience to
  see if it tells the user all the relevant
  information to be able to use the
  software/device/etc
• Changes are made according to target audience
  feedback. The document may have to be changed
  according to the problems that the target
  audience may have come across in their evaluation
  of the documentation

48
Documentation is submitted for higher authority
sign off

• Once the documentation has been checked,
  rechecked and is ready for distribution it needs
  to be given to someone with the authority to say
  that it is complete and ready to be distributed.