RIFT VALLEY UNIVERSITY

HACHALU HUNDESSA CAMPUS

HNS LEVEL III

Unit of Competency: Create Technical Documentation

Module Title: Creating Technical Documentation

LO1: IDENTIFYING AND ANALYZING DOCUMENTATION NEEDS

Identify User documentation requirements

Definition

Documentation is a package that contains Content, Format, Layout, and Language,

grammar, style to describe 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

Rift valley university Hachalu Hundessa Campus Aug, 2022 prepared by Zelalem H.
Page 1
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 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,

pseudo code, 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 mem-
ber 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 Ques-
tions).
There are many different types of user documentation depending on what users require:

Create technical documentation HNS level III. Aug, 2022 Page 2

Prepared by Zelalem H
  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 spe-
cific 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 be-
fore 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:

Examples Purpose
A project specification, training manual, user guide, tutori- to learn how to use a piece
als or help that provides step by step guidance in how to of software
use the software.
A training manual, quick reference guide or user guide to refer to a specific feature
that provides detailed commands and specifications of a of a piece of software
software package to assist with troubleshooting problems.

Create technical documentation HNS level III. Aug, 2022 Page 3

Prepared by Zelalem H
Once you have decided what the purpose of your documentation is and what type of doc-
umentation 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 document-
ation should contain and what format is most suitable.
For example, Data Entry staffs 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 ex-
ample:

User characteristic User need Possible solutions

level of computing beginner to expert create different sections for different
experience levels of experience
experience with the beginner to expert create different sections for different
particular system or levels of experience
application
frequency of use with constant, frequent to there must be initial training with some
a particular system or weekly, monthly, annu- sort of follow-up support
application ally
workplace tasks simple, repetitive tasks documentation must clearly relate to
to complex tasks the tasks at hand
work practices and eg part-time, shift work, occupational health and safety docu-
environment office, warehouse mentation is essential
language skills difficulty reading and  keep language simple, use plain Eng-
understanding written lish
language to very com-  explain technical terms and jargon if
petent readers they must be used
 avoid long uncommon words if
simple words will do

Create technical documentation HNS level III. Aug, 2022 Page 4

Prepared by Zelalem H
User characteristic User need Possible solutions
cultural background language appropriate to  use language appropriate for all
some users may not be users
appropriate for others  American spelling often appears in
documentation, since it is often
where the software originates
personal characterist- users will learn at vary- make sure individual needs are catered
ics such as aptitude, ing pace for to organisational policies
educational back-
ground, age, disability
level of confidence users might be fearful  be positive and encouraging in your
and not confident with approach
computers  avoid reinforcing negative attitudes

 It’s almost impossible to cater for all these variations. However in preparing doc-
umentation 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 con-
sistent 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 de-
termining documentation requirements.

What to include in 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).

Create technical documentation HNS level III. Aug, 2022 Page 5

Prepared by Zelalem H
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.
 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 avail-
able. 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 document-
ation.

The following table shows the advantages and disadvantages of online and paper media.

Media Advantages Disadvantages

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

Create technical documentation HNS level III. Aug, 2022 Page 6

Prepared by Zelalem H
 Information Sheet Unit of Competence Create Technical Documentation
2 Module Title Creating Technical Documentation

LO2. DESIGNING DOCUMENTATION

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, develop-
ers, 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 be-
tween. They can be specified as statements in natural language, as drawn figures, as de-
tailed mathematical formulas, and as a combination of them all.

The variation and complexity of requirements documentation makes it a proven chal-

lenge.

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-consum-
ing (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), require-
ments 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 equip-
ment), more formal requirements documentation is often required.

Create technical documentation HNS level III. Aug, 2022 Page 7

Prepared by Zelalem H
  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 re-
quirements documentation may be needed.
 If the software is a first release that is later built upon, requirements documenta-
tion is very helpful when managing the change of the software and verifying that
nothing has been broken in the software when it is modified.

Traditionally, requirements are specified in requirements documents (e.g. using word

processing applications and spreadsheet applications). To manage the increased com-
plexity and changing nature of requirements documentation (and software documen-
tation in general), database-centric systems and special-purpose requirements manage-
ment 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.

Create technical documentation HNS level III. Aug, 2022 Page 8

Prepared by Zelalem H
Online documentation
Features that may be included in online documentation are:
 table of contents hyperlinks
 tables
 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

Steps 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 ap-
proach 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.

Create technical documentation HNS level III. Aug, 2022 Page 9

Prepared by Zelalem H
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 - Analyze the audience

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

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 docu-
mentation, 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 con-
tents. 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 docu-
menting software there is often valuable information in requirement specifications, func-
tional specifications and use case documentation. This provides a basic level of informa-
tion 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.

Create technical documentation HNS level III. Aug, 2022 Page 10

Prepared by Zelalem H
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 consis-
tently, separating procedural information and reference material, determine the most ef-
fective use of images and diagrams, and making sure the information is tailored to the ap-
propriate 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.

Create technical documentation HNS level III. Aug, 2022 Page 11

Prepared by Zelalem H
 Information Sheet Unit of Competence Create Technical Documentation
3 Module Title Creating Technical Documentation

LO3. DEVELOPING DOCUMENTATION

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

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 audi-
ence 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 re-
search, 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.

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 atten-
tion; shorten, expand or delete sections; or rearrange paragraphs, sentences, or
entire topics. You will also want to edit for style, grammar and context

Create technical documentation HNS level III. Aug, 2022 Page 12

Prepared by Zelalem H
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 includes the development of docu-

mentation, manuals such as for hardware and soft-
ware, help documents, troubleshooting guides and
technical white papers and brochures.

1. Plan

Develop a technical documentation plan. The plan lists what types of technical documen-
tation are required and the target audience of each. Are they technical staffs 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 es-
timated start and end date for the document.

2. Review

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 infor-
mation, 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 application software.

3. Outline

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.

Create technical documentation HNS level III. Aug, 2022 Page 13

Prepared by Zelalem H
 Write

Begin writing the documents. Follow the KISS principle (keep it simple stupid), particu-
larly 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.

Graphics

Graphics break up the written technical information, making it easier to read. One com-
mon 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 prod-
uct being described with different views of that product.

Review

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 re-
view to make sure your document is easily understood.

Publication

Publish the document and distribute it to the intended audience. Publication options in-
cluding 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 manu-

Create technical documentation HNS level III. Aug, 2022 Page 14

Prepared by Zelalem H
als 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 cam-
eras.

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 com-
prehensive 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 edu-
cation 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 ex-
pected 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

Create technical documentation HNS level III. Aug, 2022 Page 15

Prepared by Zelalem H
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.

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 or-
der 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, chronologi-
cal, 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 au-
dience that will be reading the technical document.

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

ing the information into logical sections and levels. You can create main top-
ics 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.

Create technical documentation HNS level III. Aug, 2022 Page 16

Prepared by Zelalem H