Professional Documents
Culture Documents
1
Information Sheet Unit of Competence Create Technical Documentation
1 Module Title Creating Technical Documentation
Definition
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
User Documentation:
Technical 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 users 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
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.
Users 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:
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
Its 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 organisations
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.
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.
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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. Its 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
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.
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.
15
Graphics
Review
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
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
dont 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
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.
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.
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