Unit of Competency: Create Technical Documentation

Module Title: Creating Technical Documentation

Description: This module aims to create technical documentation which is clear
and easy for users considering knowledge, skill, and attitude.
Learning Outcome: At the end of the module the learners will be able to:
LO1- Identify and analyze documentation needs.
LO2- Design documentation.
LO3- Develop documentation.
LO4- Evaluate and edit documentation.

Contents: LO1.Identifying and analyzing documentation needs

 Consult clients to identify documentation requirements
 Interpret and evaluate documentation requirement.
 Investigate industry and documentation standards.
 Define and document scope of work.
LO2. Designing documentation
 Identify information requirements
 Create document templates and style guide
 Conduct review of the system in order to understand
its
functionality
 Extract content that meets information requirements
 Develop structure of technical documentation
 Validate technical documentation structure with the
client
LO3. Developing documentation
 Write technical documentation based on template and
scope of work.
 Trans late technical terminology
 Apply content format and style according with
relevant documentation standards and templates.
LO4.Evaluating and editing documentation
 Submit technical documentation to appropriate
person for reviewed
 Gather feedback and analyzed it.
 Incorporate alterations into the technical
documentation.

1
 Information Sheet Unit of Competence Create Technical Documentation
1 Module Title Creating Technical Documentation

LO1: IDENTIFYING AND ANALYZING DOCUMENTATION NEEDS

Overview
In this learning outcome we will discuses about how to
identify, interpret and evaluate documentation requirement,
and define and document scope of work.
Objectives:
After completing this Learning outcome the student should be
able to:
 Consult clients to identify documentation requirements
 Interpret and evaluate documentation requirement.
 Investigate industry and documentation standards.
 Define and document scope of work.

Identify User documentation requirements

Definition

Documentation is a package that contains Content, Format,

Layout, and Language, grammar, style to describes the
product to its users.

In computer hardware and software product development,

documentation is the information that describes the product
to its users or it is simply the instructions for using a
computer device or program. Documentation can appear in a variety
of forms, the most common being manuals. When you buy a
computer product (hardware or software), it almost always comes
with one or more manuals that describe how to install and
operate the product.
The term is derived from the idea that engineers and
programmers "document" their products in formal writing. The
earliest computer users were sometimes simply handed the
engineers' or programmers' "documentation." As the product
audience grew, it became necessary to add professional
technical writers and editors to the process. Today,
companies look at developing product information based on
what users actually need to do when using the product.
Documentation is now often built directly into the product
as part of the user interface and in help pages. Printed

2
technical manuals are increasingly available at company Web
sites in the form of Adobe Acrobat Portable Document Format
(PDF) files or in HTML pages. IBM and Microsoft are among
the world's largest publishers.

Categories of Documentation

Documentation is often divided into the following categories:

User Documentation:

User Documentation is the collection of documents that are

designed to help people who need to manage, operate or
maintain computer hardware or software.
It is designed for the end user of the computer hardware or
software. The user that uses user documentation may not be a
computer specialist.
Examples of user documentation are manuals, on-line help,
wizards, on-line tutorials, quick start guides, and other
written instructional information.

Technical documentation:

This is designed for the people responsible for producing or

maintaining the hardware or software.
When you buy a new computer, you generally get a certain
amount of technical documentation of the hardware, so that
you (or a technician you employ) know what upgrades and so
on are applicable to your computer.

Examples of technical documentation include: Data

documentation, flow charts, pseudocode, data flow diagrams,
Program documentation, and Hardware documentation.

User documentation
Types of user documentation:
Users might need to consult a range of documentation in order to install, configure and/or
use the functions of a system or application. For example, a new staff member using a
particular IT system for the first time needs to refer to a user guide and tutorials and
online help. In other words, they firstly need documentation that helps them learn to use
the software. As they become more familiar with the system, they will need access to
other types of documentation such as FAQs (Frequently Asked Questions).
There are many different types of user documentation depending on what users require:

3
  Instructional material – usually accompanies the
computer system, be it hardware or software, and
provides information on how to use the system or
particular aspects of it. Example:- User manual/guide.
 Training material – aims to teach people how to use a
computer system, usually a software application. It can
be used as a self-study guide or as a resource by a
trainer.
 Self-paced tutorials- teach staff how to use a system,
program, network or application to do their job. These
may be online or paper-based tutorials.
 Policies or procedures documents – describe
organizational rules and guidelines and explain how to
do a particular job or jobs. They also help with
quality assurance as a check that standard procedures
are being followed.
 Reference documentation – it is the detailed
descriptions of particular items presented in
alphabetical order. It provides neither an
instructional nor a training role; it is simply a
repository of information. It is used by users who are
already trained, to remind them of intricate details
that they cannot be expected to remember. Reference
documentation will be at the user’s fingertips while
the product is being used.
 Brochures- outline what a computer application does
 Project specifications-specifies the detailed business
requirements of the project including how the system
will work and the underlying functionality
 Reports-produced by the system, program, network or
application
 Help resources- provides online Help, quick reference
cards, scenarios, FAQs (Frequently Asked Questions).
Users can search for help on using of a specific
system, program, network or application

Purpose of user documentation:

What is the user documentation going to be used for? This is
the first question to ask before starting to create any user
documentation. When you are satisfied that you have an
answer, you can then decide what type of documentation you
are going to produce.
These are some examples of user documentation and their
purpose:

4
Examples Purpose
A project specification, training to learn how to
manual, user guide, tutorials or help use a piece of
that provides step by step guidance in software
how to use the software.
A training manual, quick reference to refer to a
guide or user guide that provides specific feature
detailed commands and specifications of of a piece of
a software package to assist with software
troubleshooting problems.
Once you have decided what the purpose of your documentation
is and what type of documentation you are going to produce,
you can look at the needs of the potential users of the
documentation.

User’s Needs
A needs analysis is a process where the needs of the target
groups for the documentation are identified and analysed.
This analysis helps to make decisions on what the
documentation should contain and what format is most
suitable. For example, Data Entry staff in a call centre
need to know how to correctly enter data in a database so
that orders can be generated correctly from a database.
For training materials and online help a needs analysis
should be conducted in person with the staff who will need
the documentation. For other documentation a look at the
needs of the users without speaking directly to staff is
sufficient.
After considering user characteristics and needs, possible
solutions can be found, for example:

User User need Possible solutions

characteristic
level of beginner to create different sections
computing expert for different levels of
experience experience
experience with beginner to create different sections
the particular expert for different levels of
system or experience
application

5
User User need Possible solutions
characteristic
frequency of constant, there must be initial
use with a frequent to training with some sort of
particular weekly, monthly, follow-up support
system or annually
application
workplace tasks simple, documentation must clearly
repetitive tasks relate to the tasks at
to complex tasks hand
work practices eg part-time, occupational health and
and environment shift work, safety documentation is
office, essential
warehouse
language skills difficulty  keep language simple, use
reading and plain English
understanding
 explain technical terms
written language
and jargon if they must
to very
be used
competent
readers  avoid long uncommon words
if simple words will do
cultural language  use language appropriate
background appropriate to for all users
some users may
 American spelling often
not be
appears in
appropriate for
documentation, since it
others
is often where the
software originates
personal users will learn make sure individual needs
characteristics at varying pace are catered for to
such as organisational policies
aptitude,
educational
background,
age, disability
level of users might be  be positive and
confidence fearful and not encouraging in your
confident with approach
computers
 avoid reinforcing
negative attitudes

6
It’s almost impossible to cater for all these variations.
However in preparing documentation for a new user, you would
obviously not confuse them with technical jargon on the
first page! You need to find a balance and remember that any
documentation must be consistent with the organisation’s
policy, conventions and standards.
For any form of documentation to be useful it must be
designed with the needs of its potential users in mind. An
analysis of the requirements of the users, and the way their
needs can be effectively addressed, is a critical step in
the process of determining documentation requirements.

What to include in user documentation

It’s a good idea at this stage to think about the content
that you will include in the user documentation. This is so
you can estimate the number of pages, the complexity of the
content and what the graphic and text components will be.
The content will have some influence on:
 design of the documentation, including layout, use of
text and graphics
 medium, eg paper-based or online
 the time and resources needed to develop the
documentation.

Media for user documentation

You can consider paper-based documentation, online
documentation or a combination of both. The media type you
choose will be influenced by the:
1 Purpose of the documentation
2 User needs and characteristics
3 Content (subject matter).
Paper media 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 staffs
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. Where user documentation
is going to be used primarily as a help tool, then online
help is most appropriate. It allows for easy searching
across the documentation.

7
Always keep in mind that you need to include a range of
items that allow users to access the required information
quickly and easily.
The following table shows the advantages and disadvantages
of online and paper media.

Media Advantages Disadvantages

Paper  conventional, most people  hard to maintain
are used to paper control of
products different versions
 easy and fast to prepare  costly to update
 inexpensive to produce
 requires readily
available software
Online  convenient  can be expensive
 easy to reach many people  requires
geographically dispersed specialised
 can be colourful and fun software
 can link to other related
documents
 easy to maintain version
control
 not costly to update

Information Sheet Unit of Competence Create Technical Documentation

2 Module Title Creating Technical Documentation

LO2. DESIGNING DOCUMENTATION

Overview
In this learning outcome we will discuses about how to
identify information requirements, create document templates
and style guide and conduct review of the system in order to
understand its
Objectives:
After completing this Learning outcome the student should be
able to:
 Identify information requirements

8
  Create document templates and style guide
 Conduct review of the system in order to understand its
Functionality
 Extract content that meets information requirements
 Develop structure of technical documentation
 Validate technical documentation structure with the client

Identify information requirements

Requirements are the description of what particular hardware or software does or shall
do. It is used throughout development to communicate what the hardware or software
does or shall do. It is also used as an agreement or as the foundation for agreement on
what the software shall do. Requirements are produced and consumed by everyone
involved in the production of documentation: end users, customers, product managers,
project managers, sales, marketing, software architects, usability engineers, interaction
designers, developers, and testers, to name a few. Thus, requirements documentation has
many different purposes.

Requirements come in a variety of styles, notations and formality. Requirements can be

goal-like (e.g., distributed work environment), close to design (e.g., builds can be started
by right-clicking a configuration file and select the 'build' function), and anything in
between. They can be specified as statements in natural language, as drawn figures, as
detailed mathematical formulas, and as a combination of them all.

The variation and complexity of requirements documentation makes it a proven

challenge. Requirements may be implicit and hard to uncover. It is difficult to know
exactly how much and what kind of documentation is needed and how much can be left
to the architecture and design documentation, and it is difficult to know how to document
requirements considering the variety of people that shall read and use the documentation.
Thus, requirements documentation is often incomplete (or non-existent). Without proper
requirements documentation, software changes become more difficult—and therefore
more error prone (decreased software quality) and time-consuming (expensive).

The need for requirements documentation is typically related to the complexity of the
product, the impact of the product, and the life expectancy of the software. If the software
is very complex or developed by many people (e.g., mobile phone software),
requirements can help to better communicate what to achieve. If the software is safety-
critical and can have negative impact on human life (e.g., nuclear power systems, medical
equipment), more formal requirements documentation is often required. If the software is
expected to live for only a month or two (e.g., very small mobile phone applications
developed specifically for a certain campaign) very little requirements documentation
may be needed. If the software is a first release that is later built upon, requirements
documentation is very helpful when managing the change of the software and verifying
that nothing has been broken in the software when it is modified.

9
Traditionally, requirements are specified in requirements documents (e.g. using word
processing applications and spreadsheet applications). To manage the increased
complexity and changing nature of requirements documentation (and software
documentation in general), database-centric systems and special-purpose requirements
management tools are advocated.

Create document templates and style guide

Designing templates
Once you have determined the documentation requirements, you can develop a template
that meets those requirements and makes the job easier. A template is a file that contains
a standard layout, styles and fonts that are used in the production of the documentation.
When you want to create a file for user documentation, you open the standard template,
usually in Word, and the layout, fonts and styles are already set up in the document. All
you need to do is start writing. Everyone uses the same template, so there is a consistent
look and feel to all of the user documentation.
The template may be:
 a Word template
 an HTML template
 an online help template.
The medium will determine what kind of template you use.

Features of templates
Paper-based documentation
Features that may be included in paper-based documentation are:
 table of contents
 columns and tables
 page and section numbering
 headers and footers
 graphics and text surrounds
 substantially chunked information.

Online documentation
Features that may be included in online documentation are:
 table of contents hyperlinks
 tables

10
  links to other pages/sites
 navigation icons
 usability/functionality
 heavy use of graphics.

Obtaining sign-off on templates

Like all documentation, templates also need to be signed-off by the relevant people. The
sign off process will be outlined in the organisational documentation policy.
The content of the template will depend on the purpose of the documentation. A template
for training materials will look quite different to a template for a procedural manual.
The template should be designed in consultation with users or a subject expert. Once the
template has been designed, it should be distributed according to the user documentation
policy, or, the agreed review process if you are working towards final sign-off.

Develop structure of technical documentation

Step 1 - Assess the purpose of the documentation

Begin the documentation process by assessing the purpose of the document. Different
documents serve different purposes. For example user guides inform a products users
how to best use a product and get the most from it, while a sales presentation's purpose is
to get the reader to buy a product. It is important to establish what you want the document
to achieve, as this will influence the rest of the documentation process.

Step 2 - Assess what tasks the users will perform

This step involves assessing the tasks users will perform, this is known as a task oriented
approach. The task oriented approach begins by focusing on how the users would use the
software or product to solve their problems or complete real world tasks.

The task-oriented approach creates more useful documentation than the functional
approach to document development, which involves describing each button and function.
The problem, with the functional approach is that it only gives the user half the story and
does not help to integrate the software or product with real world tasks that the user will
need to perform. This can often leave users with a low opinion of the software or product,
when it was really the documentation that let them down.

At the end of this stage you will have a list of tasks and sub-tasks that will provide a
skeleton for the documentation.

Step 3 - Analyse the audience

11
The audience analysis is where you create a profile that provides generic information and
any assumptions you are making about the different audiences groups the document will
have. Working from the audience analysis helps you to tailor the documentation as
closely as possible to the needs of the reader. The audience analysis is where you try to
understand who will be using the product you are documenting and what assumptions
you can make about the knowledge and skills they possess. This allows you to include the
appropriate level of detail and write using language that each audience group will
understand.

Step 4 - Develop an audience task matrix

The audience task matrix links the tasks to the different audiences that a document is
likely to have. The audience task matrix provides a useful tool for structuring the
documentation, grouping information by likely audience and if required, helping us split
a document that was too large. It also provides an additional check that all users and tasks
have been considered.

Step 5 - Create the document plans

The next step is to create the document plans based of the information from the previous
steps. This is a top down process, which you start by creating a high-level table of
contents. Then you loop between the document plan and information gathering until you
feel you have all the required content for each section.

Step 6 - Gather information

The information gathering process involves a combination of interviewing Subject Matter

Experts (SMEs) and working from existing documentation. For example, when
documenting software there is often valuable information in requirement specifications,
functional specifications and use case documentation. This provides a basic level of
information that you can build on through interviewing the SMEs.

Step 7 - Design the look and feel of the document

Designing the look and feel of the document involves deciding what format to use. For
many projects a paper document may not be the best choice, an online help system or a
web page may provide a better solution. It is important that the document looks good and
is easy to read, so you need to consider the page layout, use of white space and visual
density. You also need to take into account navigation features, so that multiple users can
navigate through the document in different ways. At this stage you must also check if
there are corporate guidelines or style guides that the document needs to adhere to.

Step 8 - Begin the writing process

Now you have a good idea of the content and a template to work with you can begin the
writing process. During the writing process you focus on presenting information

12
consistently, separating procedural information and reference material, determine the
most effective use of images and diagrams, and making sure the information is tailored to
the appropriate audience.

Step 9 - Edit and proofread the documentation

Finally you edit and proofread the documentation. You check each document against a
proofreading checklist. If there is a style guide for the documentation then base the
checklist on the style guide. This is an iterative process where the sentence structure and
clarity of the document improves with each pass.

Information Sheet Unit of Competence Create Technical Documentation

3 Module Title Creating Technical Documentation

LO3. DEVELOPING DOCUMENTATION

Overview
In this learning outcome we will discuses about how to write
technical documentation, translate technical terminology and
apply content format and style according with relevant
documentation standards and templates.
Objectives:
After completing this Learning outcome the student should be
able to:
 Write technical documentation based on template and
scope of work.
 Translate technical terminology
 Apply content format and style according with relevant
documentation standards and templates.

How to Write Technical Documentation

Technical communication or documentation is the process of conveying "user-friendly"
information through writing about a particular topic to an intended audience. Technical
documentation ranges from a business email to business reports to a user guide or help
system. Many only turn to documentation “when all else fails.” No wonder
documentation is often shoddy at best; nonexistent at worse. Computer companies may
feel that their software is so easy, they don’t need documentation. But technical
documentation is less expensive than technical support calls. Before you can develop
good technical documentation, you need to know that effective technical documentation
is a well-planned and executed mission.
Instructions

13
 1 Determine purpose and audience. You need to know why you are creating this
documentation and who will be reading it. The type of documentation you
create will be different if your audience is a car mechanic than if your
audience is a software engineer.
2 Gather information. The person creating the documentation is often a writer
and not the subject matter expert. It is important to gather the information so
that you can document it. Collecting the information can mean doing research,
interviewing a subject matter expert, or experimenting with the product itself,
as in the case of a software program.

3 Organize and outline information. You may start with an existing document or
a template. It’s important to enter what information you have and leave the
areas blank where you need to gather more information. This will be your
working document, and you will build on it. Jotting down what you do have
even if you have large areas of empty space will boost your confidence that
you are moving forward in the project.

4 Write the first draft. This is when you start filling in the blanks and allowing
for a flow of ideas to stream from your consciousness. Do not stop that flow
by revising at this stage.

5 Revise and edit. You may want to put the document away for a period of time
so that you can give it a fresh look. Then focus on topics that need more
attention; shorten, expand or delete sections; or rearrange paragraphs,
sentences, or entire topics. You will also want to edit for style, grammar and
context

Guide to Writing Good Technical Documents

Writing technical documentation is easier if you

have the proper training and a road map to follow.

Technical writing encompasses the development of

documentation, manuals such as for hardware and
software, help documents, troubleshooting guides
and technical white papers and brochures.
According to the website Klariti, some of the skills
required to be a technical writer is excellent product
knowledge or the ability to quickly understand the
technical aspects of a product, and the ability to
effectively communicate technical information to
non-technical people.

14
1. Plan
o Develop a technical documentation plan. The plan lists what types of
technical documentation are required and the target audience of each. Are
they technical staff who are well-versed in what you are writing about? Or
are they end users who have limited technical knowledge?

For each document list who will develop it, who must approve it, and the
estimated start and end date for the document.

2. Review
o The book "Technical Writing 101: A Real World Guide" recommends that
you review existing information on the topic to be written about. This
information could be internally developed material, such as software
program specifications, or externally supplied information, such as from a
software vendor.

Also seek out subject matter experts you can interview about the topic
being written about. This can shorten the time required to develop the
documentation.

Also interview users to gather non-technical information about the topic

being written about such as applicaiton software.

3. Outline
o Develop an outline for each document. An outline is the structure for how
a document is written. Not outlining your document first is like getting on
an airplane without knowing where that airplane is going. The outline
should follow a logical sequence with outline items indented so that
similar or related items are at the same level.

Write

o Begin writing the documents. Follow the KISS principle (keep it simple
stupid), particularly when writing for non-technical users. For task-
oriented documents, consider using the play script procedure writing style.

According to the website ebook 3000, for play script style writing a
procedure is written like the script in a play with each step by step action
listed and who takes each action. The play script style is easy to
understand.

Insert relevant references in your document.

15
 Graphics

o Graphics break up the written technical information, making it easier to

read. One common form of graphics to consider is a flow chart that shows
relevant items, such as the steps involved in a procedure. Other relevant
graphics might include photos of a product being described with different
views of that product.

Review

o Have your document reviewed by a competent proofreader and editor who

is acquainted with the technical subject you are writing about. Be open to
suggestions.

If the intended audience is the end user, send a draft of the document to an
end user to review to make sure your document is easily understood.

Publication

o Publish the document and distribute it to the intended audience.

Publication options including printing it using a photocopy machine, using
an in-house printing facility if one exists in your company, or outsourcing
the document.

It is recommended that you also publish the document in a pdf format so

that it can be easily distributed through email.

Keep all pre-publication material on file so that when revisions are

required in the future you can easily access the original material.

Definition of Technical Writing

Technical writing can turn into printed manuals or online guides.

Technical writing is a method of researching and creating information about technical

processes or products. That information can then be distributed to users as printed
manuals or online guides so they can perform tasks. Examples of technical writing
include car repair manuals, help text for database software and FAQs for troubleshooting
cameras.

1. Judging Quality
o Good technical writing is concise, easy-to-read and organized according to
task (e.g. "how to erase files") rather than feature (e.g. "file erase menu
option"). It must make information easy to find through the use of a

16
 comprehensive table of contents, extensive index, well-organized tables
and useful diagrams.

Hard Copy

o Printed manuals are expensive to produce, distribute and update, but they
don’t require a computer to use. They may be the only alternative where
portability is needed, such as for on-site repair or field work.

Soft Copy

o Online writing is inexpensive to produce, and easy to distribute and update

by computer media or the Internet. Because they require a computer to
use, they are required for computer software.

Learning the Profession

o Technical writing combines a technical background with writing skills.

Community colleges can teach the basics of both. From there, formal
education can range all the way to a doctoral degree.

Jobs

o Writing samples are the quickest way to assess the skill of a potential hire.
How do his writing and technical skills balance? The more a writer is
expected to work without the help of a technical expert, the more
important his technical expertise becomes.

How to Outline Technical Writing Documents

A well-written document isn't created by chance.

The material covered in a report, manual or other
technical document is planned, organized and then
written. The outlining stage of a document is a key
step and chances are the information won't be
presented logically if an outline isn't created.
Outlining gives the author a chance to think about
the information that should and shouldn't be
included.

17
Instructions

1 Brainstorm your ideas. Write down any ideas in your outline that you think
should be included in the technical document. Don't be concerned with the
order of the information. It just matters that all of the information is included
in the brainstorming process.
2 Determine the purpose of the technical document. Ask yourself questions such
as who will be reading the document, why will it be read and how will it be
used.

3 Decide what type of outline you would like to create: historical,

chronological, specific to general, small to large, simple to complex or any
other form appropriate to the content. Think about the audience and about the
information that you want to present. Make sure that the way the information
is arranged makes the most sense to the type of information being presented
and to the audience that will be reading the technical document.

4 Arrange the information in the appropriate order. An outline involves

grouping the information into logical sections and levels. You can create main
topics and sub-topics and sub-sub-topics.

5 Finish the outline by reviewing the information to verify that the subjects are
organized appropriately and logically. Make sure that you aren't missing any
key facts. Delete any information that isn't relevant to the technical document.

18