developing e-learning content - web viewdate last saved: 1 december 2011 by michelle kennedy....

Unit NotesICAICT301A Create user documentationTopic 2 – Produce user documentation

© Copyright, 2023 by TAFE NSW - North Coast Institute

Date last saved: 20 December 2011 by Michelle KennedyAlexandra Miller Version: 1.3 # of Pages = 3

Copyright of this material is reserved to the Crown in the right of the State of New South Wales. Reproduction or transmittal in whole, or in part, other than in accordance with the provisions of the Copyright Act, is prohibited without written authority of TAFE NSW - North Coast Institute.

Disclaimer: In compiling the information contained within, and accessed through, this document ("Information") DET has used its best endeavours to ensure that the Information is correct and current at the time of publication but takes no responsibility for any error, omission or defect therein. To the extent permitted by law, DET and its employees, agents and consultants exclude all liability for any loss or damage (including indirect, special or consequential loss or damage) arising from the use of, or reliance on, the Information whether or not caused by any negligent act or omission. If any law prohibits the exclusion of such liability, DET limits its liability to the extent permitted by law, to the re-supply of the Information.

Third party sites/links disclaimer: This document may contain website contains links to third party sites. DET is not responsible for the condition or the content of those sites as they are not under DET's control. The link(s) are provided solely for your convenience and do not indicate, expressly or impliedly, any endorsement of the site(s) or the products or services provided there. You access those sites and use their products and services solely at your own risk.

of 12

ICAICT301A Create User Documentation

Table of ContentsGetting Started with ICAICT301A Create User Documentation.............................42. Produce user documentation................................................................................5

Types of user documentation...................................................................................5

Activity 2.1: Types of documentation................................................................6

Providing support to clients for macros/templates....................................................6

Reviewing the system, program, network or application..........................................6

Writing effective user documentation........................................................................7

Activity 2.2: What makes a good user guide?..................................................8

Tips for writing and designing effective user documentation....................................8

Activity 2.3: Creating a user guide....................................................................9

Involving business units in the development of user documentation........................9

Developer tools.......................................................................................................10

Quality Assurance (QA)..........................................................................................11

QA checklist............................................................................................................11

Usability testing.......................................................................................................12

Activity 2.4: Usability.......................................................................................12

Check Your Understanding.....................................................................................12

of 12


Getting Started with ICAICT301A Create User DocumentationThese unit notes have been developed to provide a learning pathway to competence in ICAICT301A Create User Documentation. The notes contain all the skills, knowledge and learning required to achieve competence. The learning process includes:

Reading and discussing the content with your instructor

Discussing your experience with the content – how can you apply the content in your work?

Answering simple questions both in writing and in discussion

Performing simple learning activities – researching, reflecting, searching on the Internet, completing tasks and creating notes for your own reference

After completion of this unit you will be able to demonstrate your skills and knowledge in creating user documentation in relation to the following competencies:

Determine documentation standards and requirements

Produce user documentation

Review and obtain sign-off

Using the Unit NotesIcons and symbols are used throughout the guide to provide quick visual references. They indicate the following:

Icon Meaning Icon MeaningACTIVITY: An activity is listed to be completed

ACTIVITY: A Learning activity requiring some physical action

WWW: A web link is listed REFLECTION: A point is to be considered and thought about more deeply

IMPORTANT: A pivotal point is detailed

SEARCH: A particular item / book etc needs to be found and applied

of 12


Produce user documentation

Types of user documentationWhen a new computer application is implemented or changes are made to existing computer applications, documentation that explains how the computer application works may need to be provided directly to users and/or to the help desk.

There are different types of documentation that can be available for each computer application, for example:

1. user manual/guide

2. technical manual/guide

3. training manual/resources.

When software is purchased off-the-shelf it usually comes with a user guide and technical guide. Training resources are then either purchased or developed in-house.

When computer applications are developed internally, a user guide, technical guide and training resources are usually developed to support the application. If the development is outsourced then the same supporting materials are usually developed as part of the project.

Outsourcing occurs when external staff are hired to develop the computer application.

So client documentation for software applications is generally prepared by the people/organisation who design and develop the application.

A user guide shows the user:

how to use the application, ie the steps required to complete various tasks

screens shots with ‘dummy’ data to give the user a complete picture of how to enter data and process the data

tutorials.

Note that this guide can incorporate a training resource such as a tutorial.

The technical manual generally contains the technical information such as:

system requirements to run the application

how to install the application

configuring the application

database layout (if a database is used)

screen layouts

how to get technical support.

At the end of any project to develop a computer application, a copy of all documentation should be provided to the client and the technical unit.

of 12


Activity 2.1: Types of documentationCan you think of any other types of documentation that may be used to support a software application or other software (apart from user guides)?

Providing support to clients for macros/templatesJust like computer applications, macros and templates need to be supported by the help desk. When new templates have been developed or new macros set up in standard software packages, copies of the templates and lists of macro codes and their purpose should be sent to the help desk.

When staff members contact the help desk because a template is being troublesome or a macro is not working, they can consult these documents to assist the staff member.

Reviewing the system, program, network or applicationBefore you can start writing documentation, you need to know how the system, program, network and/or application that you are documenting works.

Using a user’s perspective

The only way to find out how the system, program, network or application works is to become a user so that you become familiar with its features and you are confident in using it.

You should be looking at:

the functionality — how it works

the work processes surrounding its use — how the system works with organisational processes and procedures.

Another valuable source of information are staff members who are already users or project team members who have been working with the system.

Gathering existing documentation

If you are writing documentation for an existing system, program, network and/or application, some documentation may already exist. You should consult any existing documentation that may have accompanied the system (including technical information). This could include:

user guides

of 12


project specifications

online help

procedure manuals.

These documents will show you how the system, program, network or application works. It should also show you what the organisation’s work procedures are and how to apply them.

Writing effective user documentationAs a confident user of the system you can begin to write the documentation using the agreed template and relevant tools. You will need a template for user documentation and the relevant tools for development.

Planning content

In the same way that you plan any piece of writing, you will need to create a plan for writing the documentation. Before you write the user documentation, write an outline of the contents. Organise the content into:

1. main headings

2. sub headings

3. points under each of the subheadings.

It might be necessary to approach a subject matter expert to assist with the planning or it might be sufficient to use any existing documentation as a model for the new documentation.

When writing the content, it is important to follow effective writing principles. Other features such as graphic design and navigation will help user documentation work for users. Along with getting the content right, you’ll need to use sound principles for layout and usability as well.

A final stage in the development of your documentation will be testing the documentation with real users, then revising the documentation and testing it again. So you’ll have the opportunity to adjust content and other features to better fit the needs of your target users.

Reflect

Think about the features that you have found useful in documentation. What were they?

of 12


Activity 2.2: What makes a good user guide?

1. In your home, locate a manual that you think is effective for how to use a home appliance, or other technical equipment such as a microwave, clock radio, dvd player, computer peripheral, etc.

2. Look at the manual and try to identify features that make the manual a good ‘user guide’. List those features in the table below:

Tips for writing and designing effective user documentationUse this as a checklist for planning the features of user documentation.

Content features

Give a brief introduction where you state the purpose and objectives of the documentation.

Include a table of contents or index.

When writing, keep the users’ needs in mind, i.e. put yourself in the users’ place.

Ensure the content is accurate.

Make clear sections for different types of features/information.

Break the content down into easy-to-digest ‘chunks’, e.g. using paragraphs and sub headings, or multiple screens.

Use illustrations, diagrams, charts and/or screen shots where appropriate.

State instructions clearly and step-by-step.

Use plain English and avoid jargon.

of 12


Use technical terms only where necessary.

Include a troubleshooting or help section.

Include a glossary of the technical terms you have used.

Layout features

- Make the document structure as simple as possible and logical by providing cues to locate information.

- Ensure good usability, especially for online documentation.

- Cross-reference information, eg use hyperlinks in online documentation.

- Warnings, comments and help should be well-organised and visible.

- Aim for a clean design for text styles and layout that is consistent across all pages.

Activity 2.3: Creating a user guide

1. Think about what is involved in using an Internet browser application to go to a specific website eg Safari, Internet Explorer, Firefox.

2. Break down this task into simple instructions for a beginner. List the steps as you would in a user guide:

of 12


Involving business units in the development of user documentationOne of the reasons a project could fail is that people in the business units who will be impacted by the project’s implementation have been left out of the consultation process. From the beginning to end of a project, project team members need to work closely with users. They are an invaluable resource for developing documentation.

Though users and subject matter experts from the business units might not have the skills necessary to write effective documentation, they have the content knowledge. If you can tap into this knowledge your content will be accurate and relevant.

ReflectWhat do you think may be the benefits of involving users and accepting their feedback?

Developer toolsThe writing tools you use will be determined by the medium — paper-based or online. Tools (software) can include applications for:

word processing

image editing

image conversion (to web-ready)

painting and drawing

HTML conversion/authoring/editing

FTP utility

site management software

multimedia or slide show authoring

audio and video equipment and editing software

If you are developing paper-based materials, useful tools are:

word processing software, e.g. Microsoft Word

imaging software, e.g. Adobe Photoshop and/or Adobe Illustrator.

of 12


If your materials are going online, useful tools are:

HTML conversion/authoring/editing

imaging software, e.g. Adobe Photoshop or Fireworks

FTP utility, e.g. FTP Pro or CuteFTP.

Quality Assurance (QA)Once the documentation has been written, a quality assurance check should be conducted before the draft is sent out for review. This check is best done by a subject matter expert, another member of the project team, or a different writer.

QA checklistA standard checklist should be used to check the documentation. A QA checklist contains a list of standard formats and styles that reflect the organisation’s user documentation standards.

The purpose of the checklist is to ensure the documentation standards are followed and that all user documentation is consistent in style and appearance. Once the QA is complete, the documentation can be sent for a formal review.

Search on the Internet for some QA checklists, or look at your QA standards at work.

In a table list down some of the criteria you could include in a QA checklist. The first three are provided as an example of the type of criteria and evidence you should look for:

Table 1: QA checklist

Criteria Evidence to look for

Is the medium suitable? consider work practices, frequency of updates

Is the documentation suitable for the intended audience?

plain language

terms explained

user-centred

Presentation document looks interesting to read

of 12


Criteria Evidence to look for

Usability testingOnline user documentation requires a test for usability. This means that the interactive design and navigation should be tested to see whether the user can easily find the information they are after.

It is preferable for usability testing to be performed by a subject matter expert or a user (since they will be using the documentation when it is finished). The organisation’s usability standards can be put into the QA checklist.

Activity 2.4: Usability

1. Using the same manual you found for the previous activity, conduct a usability test. For example, think about some specific information you want to find and see how easy it is to find it.

2. What was the information or instruction easy or difficult to find?

Check Your Understanding1. I can now

List the steps in a user guide Conduct a usability test Identify features that make a manual a good ‘user guide’ List the types of documents that may be used to support application or

other software Create a QA checklist

of 12


developing e-learning content - web viewdate last saved: 1 december 2011 by michelle kennedy....

Documents