4. create client user documentation and 5. obtain endorsement/sign-off

3651A Create User & Technical D3651A Create User & Technical Documentationocumentation

11

4. 4. Create client user Create client user documentationdocumentation

andand

5. Obtain endorsement/sign-off5. Obtain endorsement/sign-off


22

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

User DocumentationUser Documentation


33

Types of user Types of user documentationdocumentation

In unit 1 you learnt that user documentation In unit 1 you learnt that user documentation can be printed or online, and assists people can be printed or online, and assists people (that is, users) to use a computer system. (that is, users) to use a computer system. You looked at different types of user You looked at different types of user documentation (instruction, training, policy documentation (instruction, training, policy and procedures).and procedures).

User documentation can take various forms, User documentation can take various forms, depending on the needs of the audience depending on the needs of the audience and the scope of the project. The forms of and the scope of the project. The forms of documentation include:documentation include:


44

user’s reference guidesuser’s reference guides quick reference cardsquick reference cards handbookshandbooks keyboard templateskeyboard templates wall chartswall charts training manualstraining manuals computer-managed learningcomputer-managed learning computer-based trainingcomputer-based training tutorialstutorials wizardswizards cue cardscue cards frequently asked questionsfrequently asked questions glossariesglossaries troubleshooting informationtroubleshooting information navigation aidsnavigation aids context-sensitive helpcontext-sensitive help access to documentation on the access to documentation on the

InternetInternet intranet documentation.intranet documentation.


55

User’s Reference guide User’s Reference guide

Containing comprehensive information Containing comprehensive information about the software. There purpose is to:about the software. There purpose is to:

enable users to learn how to use the software, enable users to learn how to use the software, provide accurate reference info, provide accurate reference info, supply step-by-step details about how to supply step-by-step details about how to

complete tasks using the software, complete tasks using the software, help users understand their role in the processhelp users understand their role in the process explain why, as well as how a process is explain why, as well as how a process is

performed. It can be structured as task-based performed. It can be structured as task-based procedures or as menu-driven screen procedures or as menu-driven screen descriptions.descriptions.


66

Quick Reference cards Quick Reference cards

Day to Day prompts of how to Day to Day prompts of how to complete tasks. There purpose is to:complete tasks. There purpose is to:

list key functionslist key functions act as a memory jogger about what to act as a memory jogger about what to

do nextdo next summarise informationsummarise information match the needs and level of expertise match the needs and level of expertise

of specific usersof specific users


77

Handbooks Handbooks

Handbooks are scaled down documents that Handbooks are scaled down documents that provide basic information to business provide basic information to business partners or outside contractors who may partners or outside contractors who may need to supply or use data. Can also be need to supply or use data. Can also be written for software users who do not need written for software users who do not need the full details contained in the user’s the full details contained in the user’s reference manual. reference manual.

Purpose is to Purpose is to summarise key functions used by target audiencesummarise key functions used by target audience provide step-by-step instructionsprovide step-by-step instructions help users to use the software confidently and help users to use the software confidently and

accurately.accurately.


88

Keyboard templates Keyboard templates

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


99

Wall charts Wall charts

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


1010

Training manualsTraining manuals

Training manuals are usually only prepared Training manuals are usually only prepared when there is an organised training when there is an organised training program. A training manual has a different program. A training manual has a different role from that of a user’s reference guide, role from that of a user’s reference guide, and requires a different approach. The and requires a different approach. The purpose of a training manual is to:purpose of a training manual is to:

build user acceptance of the software. Most build user acceptance of the software. Most people have an automatic reluctance to use or people have an automatic reluctance to use or learn something new, and the training manual learn something new, and the training manual must make the transition easy and painless.must make the transition easy and painless.


1111

provide users with customised working examples provide users with customised working examples of how to perform a task using the software. This of how to perform a task using the software. This means that different training manuals must be means that different training manuals must be prepared for each user group. The examples used prepared for each user group. The examples used for training data-entry clerks will be different for training data-entry clerks will be different from the examples used for training sales stafffrom the examples used for training sales staff

lead the audience through the user’s reference lead the audience through the user’s reference guide, so that they have some familiarity with it guide, so that they have some familiarity with it and are therefore more likely to accept it and use and are therefore more likely to accept it and use itit

provide a structure for trainers to follow so that provide a structure for trainers to follow so that the training delivery is consistent in content and the training delivery is consistent in content and approachapproach

give realistic activities so that users can practise give realistic activities so that users can practise in a controlled environment.in a controlled environment.


1212

Computer-managed Computer-managed learning (CML)learning (CML)

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


1313

Computer-based training Computer-based training (CBT)(CBT)

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


1414

TutorialsTutorials

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


1515

WizardsWizards

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


1616

Frequently asked questions Frequently asked questions (FAQ)(FAQ)

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


1717

GlossariesGlossaries

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


1818

Troubleshooting Troubleshooting informationinformation

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


1919

Navigation aidsNavigation aids

For some applications the online documentation is For some applications the online documentation is vast, and so being able to navigate around the vast, and so being able to navigate around the documentation easily is very important. Helpful documentation easily is very important. Helpful navigation aids include:navigation aids include:

contents menuscontents menus indexes with A—Z buttons to go straight to the area of indexes with A—Z buttons to go straight to the area of

interestinterest browse sequences, in which related topics are grouped browse sequences, in which related topics are grouped

together so they can be skimmed using browse buttons together so they can be skimmed using browse buttons (browsers)(browsers)

search facilities to enable the user to find topics relating search facilities to enable the user to find topics relating to a particular key word.to a particular key word.


2020

Context-sensitive helpContext-sensitive help What the user wants is relevant help. What the user wants is relevant help.

Ideally, they should be able to find it Ideally, they should be able to find it immediately rather than having to search immediately rather than having to search for it. for it.

Documentation on the InternetDocumentation on the Internet Help can often be found on the Internet in the form Help can often be found on the Internet in the form

of information about a product, answers to FAQ of information about a product, answers to FAQ and so on. Websites can also provide fixes and and so on. Websites can also provide fixes and upgrades for users to download. This is a cheap upgrades for users to download. This is a cheap and effective means of distributing software.and effective means of distributing software.


2121

Intranet documentationIntranet documentation

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

Activity 3.1


2222

Purpose of User Purpose of User DocumentationDocumentation

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


2323

UnderstandingUnderstanding

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


2424

TrainingTraining

Most users require some form of training. Most users require some form of training. Formal training sessions with a human trainer Formal training sessions with a human trainer can be very effective, but often computer can be very effective, but often computer users do not attend them. Instead, lacking users do not attend them. Instead, lacking time and facilities for adequate training, time and facilities for adequate training, many make do with a trial-and-error many make do with a trial-and-error approach.approach.

User documentation for training can come in User documentation for training can come in any form of media. User manuals may include any form of media. User manuals may include a tutorial section that takes the user through a tutorial section that takes the user through the steps of a common task or set of tasks. the steps of a common task or set of tasks.


2525

ReferenceReference

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

Activity 3.2


2626

Developing user Developing user documentationdocumentation

In unit 1, we looked at the standard In unit 1, we looked at the standard documentation process, which consists of documentation process, which consists of the following steps:the following steps:

Planning.Planning. Drafting.Drafting. Reviewing.Reviewing. Testing.Testing. Producing.Producing. Distributing.Distributing. Updating.Updating.


2727

Before starting to write documentation, Before starting to write documentation, you should plan what to do. Planning you should plan what to do. Planning now can help you provide now can help you provide documentation that satisfies the documentation that satisfies the prime objective of supporting the prime objective of supporting the user. Planning involves:user. Planning involves:

investigating the probleminvestigating the problem defining the target audience — their skill level defining the target audience — their skill level

and needsand needs determining documentation requirementsdetermining documentation requirements designing the documentationdesigning the documentation selecting suitable methods.selecting suitable methods.


2828

Investigating the problemInvestigating the problem

When deciding what documentation is required for When deciding what documentation is required for a particular computer system, you need to find a particular computer system, you need to find out more about the computer system to be out more about the computer system to be documented. A number of questions need to be documented. A number of questions need to be asked, such as:asked, such as:

Is the package a simple program, or is it likely to Is the package a simple program, or is it likely to require a large amount of online assistance for a require a large amount of online assistance for a variety of users at different skill levels?variety of users at different skill levels?

What operating system (s) is the software designed What operating system (s) is the software designed for?for?

I Is the product an upgrade of a previous version? If I Is the product an upgrade of a previous version? If so, perhaps a ‘What’s new’ section may be required.so, perhaps a ‘What’s new’ section may be required.


2929

The purpose of the documentation The purpose of the documentation needs to be clearly stated. For needs to be clearly stated. For example, for a sales support example, for a sales support application it may be:application it may be:

To enable novice users to operate the three To enable novice users to operate the three major functions of the application by following major functions of the application by following a step-by-step tutorial.a step-by-step tutorial.

To allow the average user to complete the To allow the average user to complete the tutorial in twenty minutes.tutorial in twenty minutes.

To enable the user to:To enable the user to:

add clientsadd clients search for and retrieve/modify client details.search for and retrieve/modify client details.


3030

Defining the target Defining the target audienceaudience

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


3131

Novice: Novice: A novice is a user who has not had any A novice is a user who has not had any

exposure to the application but must be exposure to the application but must be able to become proficient in using it.able to become proficient in using it.

Intermediate: Intermediate: The intermediate user has had initial The intermediate user has had initial

training. They have used the application to training. They have used the application to a degree where they are familiar with the a degree where they are familiar with the major functions and can perform most of major functions and can perform most of their duties with that application. their duties with that application.


3232

Expert: Expert: Expert users have had advanced training or have Expert users have had advanced training or have

used the application for an extended period. They used the application for an extended period. They have extensive knowledge of the application and have extensive knowledge of the application and are proficient users. A reference card would be are proficient users. A reference card would be suitable.suitable.

Casual: Casual: Casual users use the application for specific functions Casual users use the application for specific functions

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


3333

Determining Determining documentation documentation requirementsrequirements

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


3434

Your design should specify:Your design should specify:

standards and styles — for text and graphicsstandards and styles — for text and graphics graphics — how they will fit into the page layoutgraphics — how they will fit into the page layout topics — which will be covered or addressed and topics — which will be covered or addressed and

at what level. This should be consistent with user at what level. This should be consistent with user needs and characteristics.needs and characteristics.

style and tone — these help determine the style and tone — these help determine the impression the documentation will make on the impression the documentation will make on the user. This should be compatible with such things user. This should be compatible with such things as the language, culture and attitudes of the as the language, culture and attitudes of the user.user.

typographic standards (for example, font size typographic standards (for example, font size and type) — these will influence the reader’s and type) — these will influence the reader’s ability to understand the documentation. ability to understand the documentation.


3535

Designing documentation is a three-Designing documentation is a three-stage process:stage process:

designing the overall structure of the designing the overall structure of the help topics, also referred to as pages or help topics, also referred to as pages or screensscreens

designing the links that enable designing the links that enable navigation around the systemnavigation around the system

designing the contents of each screen.designing the contents of each screen.


3636

Selecting suitable tools to Selecting suitable tools to develop the documentationdevelop the documentation

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


3737

DraftingDrafting

Drafting is the actual writing (or authoring) Drafting is the actual writing (or authoring) of the documentation, and is usually the of the documentation, and is usually the most time-consuming task. Several writing most time-consuming task. Several writing techniques can be used to make the techniques can be used to make the documentation understandable to the user, documentation understandable to the user, and these are discussed in this section. and these are discussed in this section.

At the end of each day you should always At the end of each day you should always back up your files. Every writer knows the back up your files. Every writer knows the frustration of files being corrupted or frustration of files being corrupted or damaged and not adequately backed up. damaged and not adequately backed up.


3838

ReviewingReviewing

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


3939

Some of the things that are checked are:Some of the things that are checked are:

ContentContent Is the information correct? Is there any information Is the information correct? Is there any information

omitted that should be in? Is there any information that omitted that should be in? Is there any information that is irrelevant and should be omitted?is irrelevant and should be omitted?

GrammarGrammar Is the documentation grammatically correct? AreIs the documentation grammatically correct? Are there spelling errors?there spelling errors?

Standards Standards Are organisational standards followed?Are organisational standards followed?

ClarityClarity Is the documentation clear and understandable to the Is the documentation clear and understandable to the

reader?reader? InterestInterest

Does the documentation hold the reader’s interest?Does the documentation hold the reader’s interest?


4040


4141

Writing styleWriting style The style of writing is an important factor in The style of writing is an important factor in

determining the quality of documentation determining the quality of documentation (both online and printed). The following (both online and printed). The following features can influence how well the features can influence how well the documentation is understood by the reader:documentation is understood by the reader:

languagelanguage word simplicityword simplicity sentence and paragraph lengthsentence and paragraph length spelling and grammarspelling and grammar consistencyconsistency active voiceactive voice word emphasis.word emphasis.


4242

Printed documentationPrinted documentation

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


4343

Activity 3.5


4444

Online documentationOnline documentation

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


4545

Activity 3.6


4646

SummarySummary

The three basic purposes of user The three basic purposes of user documentation are understanding, training documentation are understanding, training and reference.and reference.

A general methodology has the following steps:A general methodology has the following steps:

Planning.Planning. Drafting.Drafting. ReviewingReviewing TestingTesting ProducingProducing DistributingDistributing Updating.Updating.


4747

4. Obtain endorsement/4. Obtain endorsement/sign-offsign-off

Developed documentation is reviewed by Developed documentation is reviewed by target audience. After documentation has target audience. After documentation has been completed it needs to be tested by been completed it needs to be tested by the target audience to see if it tells the the target audience to see if it tells the user all the relevant information to be able user all the relevant information to be able to use the software/device/etcto use the software/device/etc

Changes are made according to target Changes are made according to target audience feedback. The document may audience feedback. The document may have to be changed according to the have to be changed according to the problems that the target audience may problems that the target audience may have come across in their evaluation of have come across in their evaluation of the documentationthe documentation


4848

Documentation is Documentation is submitted for higher submitted for higher

authority sign offauthority sign off

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

4. create client user documentation and 5. obtain endorsement/sign-off

Documents