Occupational Standard: Hardware and

Network Servicing Level III

Unit Title : Create Technical

Documentation

Unit Code: ICT HNS3 04 0714

1
Learning Outcome1: Identify and analyze
documentation needs
Documentation
 Documentation is needed in order to install,

configure and/or use the functions of a system or

application.
Media for user documentation
 Paper-based documentation,
 Online documentation or
 a combination of both.
 The media type you choose will be influenced by
the:
 Purpose of the documentation 2
 User needs and characteristics
 Content (subject matter).
 There are advantages and disadvantages to
online and paper media.

Media Advantages Disadvantages

Paper • Conventional, most • Hard to maintain
people control of different
are used to paper versions
products • Costly to update
• Easy and fast to prepare
• inexpensive to produce
• requires readily
available
software
Online • Convenient • Can be expensive
• Easy to reach many • Requires specialised
people software
geographically
dispersed 3
• Can be colourful and fun
• Can link to other related
 Paper is appropriate in most circumstances. It is
the most commonly used method of delivering
documentation, so most people are used to it and
like it.
 However, when staff are dispersed across a

country or around the world, online delivery is

best. Everyone can access the same
documentation and only one version is available.

4
Types of user documentation
 When 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. 5
A user guide shows the user:
 How to use the application, i.e. the steps required

to complete various tasks

 Screen shoots with data to give the user a complete

picture of how to enter data and process the data

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

Learning Outcome2: Design documentation

Writing effective user documentation

 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:

a) Main headings

b) Sub headings

c) Points under each of the subheadings.

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

 Make clear sections for different types of
features/information.
 Break the content down into easy-to-digest ‘chunks’, eg

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.

 Use technical terms only where necessary.

 Include a troubleshooting or help section.

8
 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, e.g. 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.

9
Developer Tools
 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.
 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 Cute FTP

10
Learning Outcome 3. Develop Documentation
Establishing a polite and professional
manner
 Most jobs in the IT industry require you to

interact regularly with clients. Some of these

interactions include:
 attending to customers’ enquiries and
complaints
 determining a client’s needs

 obtaining feedback from a client with regard to

an installation, customisation, or support issue

 providing a client with information

 Providing instruction to a client.

 When dealing with clients, it is important for

11
you to ensure you establish and maintain a
courteous and professional manner.
 Courteous behavior
 Behaviour that is considered courteous is:
 being friendly
 showing respect for the other person, and
 Assisting the other person.
 Being courteous is an important element of
being professional.

12
 Professional behavior
 When dealing with clients in a workplace

setting, professionalism is critical. Behaviour

that is considered professional is:
 being polite
 focusing on the needs of the client
 assisting the client to meet their needs
 following organisational policies and
expectations of good conduct
 Ensuring the client’s needs have been met.
 Another key element to professionalism is
doing all of the above within an appropriate
timeframe.

13
 What do you think may be the benefits of
involving users and accepting their
feedback?
 The end product is more closely aligned
with the needs of the users.
 The process of creating user
documentation is much simpler due to the
expert knowledge users bring.
 Implementation and take-up of the new
system, program, network or application is
much greater with user involvement, as
the subject matter experts can act as
‘champions’ within the business units.

14
 Some of the things the IT Support person
needs feedback on include:
A need — What does the client need? Have I
understood the needs of the client correctly?
 The solution — How can I meet the client’s
needs?
 The implementation — Has the implemented
solution worked?
 The IT department will require the three
types of feedback if it is to resolve client
problems.

15
LO 4. Evaluate Documentation
 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.

16
 Quality Assurance Checklist
Criteria Evidence to look for
Is the evidence suitable? • consider work practices,
frequency of updates
Are the purpose and objectives • objectives stated
clear? • outcomes measurable
• achievable given the stated
skill level of intended users

Is the documentation suitable • plain language

for the intended audience? • terms explained
• user-centred
Is the skill level of the user
stated? • skills required to understand
and perform tasks specified

Is the content complete and • clear sections

well organised? • pages/screens numbered
• summaries included
• trouble shooting section
included 17
•content matches objectives
Is it easy to access and navigate Access points include:
the information? • table of contents
• well-developed index with
• accurate matches
• cross referencing
• hot spots (online)
• glossary
• legend to explain any symbols
Are instructions clear? • one task in one instruction
• instructions are numbered
• technical jargon avoided,
explained where necessary, and
located in the glossary
Logical flow of information • topics build on the preceding
topic and increase in level of
difficulty
Ease of use • users can find what they are
looking for
• users understand it 18
• users believe it is complete and
accurate
Visual Cues • adequate use of tables, illustrations,
colour and other visual elements
• different kinds of information are
clearly identified for easy reading eg
•Heading
• main body text
• instructions for user to perform a task
at the computer
• explanations of tasks
• warnings
• screen shots
• system messages
• comments to the user
• shortcuts to functions: function keys
Consistency in layout • heading styles used consistently
• consistent use of fonts, type and size
for both headings and body text
• font types limited to two or three
• consistent use of colour, paragraph
styles, etc 19
Balance of text and white space • adequate use of white space
information is easy to read and
follow
• left justification been used

Presentation document looks interesting to

read

20