Training, Teaching and Learning Materials (TTLM)

ADMAS UNIVERSITY

The Ethiopian TVET-System

HARDWARE & NETWORK SERVICING
Level – III

Learning Guide
Unit of Competence: Create Technical Documentation
Module Title: Creating Technical Documentation
LG Code: EIS HNS3 040811
TTLM Code: EIS HNS3M 040811

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 2 of 73
Compiled by: ICT Department
 LO1: IDENTIFY AND ANALYZE DOCUMENTATION NEEDS

Inside this reading

Technical documentation basics 3

The importance of documentation 3
Basics of form and function 4
A broad view of requirements 4
Document management and version control 4
Defining the scope of work 6

Working out what is required 6

From broad questions to details 6
Collecting requirements 8
Evaluating requirements 9
Reviewing requirements to come up with specifications 9
Validating requirements 10

Summary 12
Progress 12

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 2 of 73
Compiled by: ICT Department

Ver
Technical documentation basics
Figure 1 below helps map the process of creating technical documentation, where requirements
and standards are on an equal level as starting points in the process.

Figure 1: The place of requirements gathering in creating technical documentation

Before gathering and validating requirements for any particular documentation to be created or
reviewed, it helps to understand some basic requirements as they apply in general and to all
forms of technical documents.
The importance of documentation
There are many ways by which the importance and purpose of documentation might be
neglected. The experience of increasing paperwork and computerised work flow systems,
added to email, internet, intranet and the range of forums in organisations, can altogether lead
to a feeling of information overload. At such times documents can easily be overlooked and
lost. The idea of working on documentation may have less appeal than working on a computer
desktop.
Yet any sense of dread and futility related to documentation is misplaced. Documentation is
crucial in many respects. Collectively, it is the means by which an organisation systematically
understands
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 3 of 73
itself and its purpose, to then develop and grow. In the IT industry, fulsome documentation is
also a basic requirement for finished work to meet client needs.
In the information age businesses are built on platforms that process, capture and disseminate
information, and that platform is supported in all its parts by a range of technical
documentation.
Basics of form and function
A technical document may be a form, report, product specifications, records, engineer‟s test results,
benchmark details, an operating manual, photograph, a schematic diagram, or minutes of a meeting.
A technical document can also exist in any media. For instance, details about a network
configuration can be stored on paper, CD, word processing file, as code, in a database or
through intranet files on the web.
Managers, technical staff and operators all use documentation. Technical and operating manuals
are highly visible examples of the documentation that is typically produced by a project, such as
the installation of a local area network, as an example. The audience for such technical
documentation would be IT specialists who develop and maintain software and hardware, and
the documents would include text and diagrams about the system, including software and
hardware.
Technical documentation must be accurate, complete, and accessible. Complete illustrations,
facts, figures, numbers and conventions that support and inform the people who will use the
documentation must all be considered when planning documents.
A broad view of requirements
To incorporate all those elements and know what exactly is needed demands a good
understanding of the purpose and audience for a document. This understanding may be due to
the composer being an expert in that area. To cite our example above, you may have worked on
the LAN from design through to implementation and staff training. You will then probably need
someone to review that document to ensure its technical accuracy, and ideally a third „pair of eyes‟
to correct any mistakes and ensure that it clearly expressed and accessible to most readers.
If you are to create technical documentation outside your knowledge or skill area, you will need
the advice, input and reviews from technical experts within the organisation or reliable advisors
from outside. Both examples can require a detailed understanding of businesses, technical,
operational and information needs, which is gained by a process of collecting and analysing
requirements.
Requirements begin with an understanding the goals of the organisation. This is then followed
by the goals of stakeholders in a particular product or project or area, such as users,
customers, suppliers or policy-makers.
Document management and version control
In some organisations, vital information is trapped in piles of paper, locked in filing cabinets or
scattered among incompatible files. In others, the content is stored on servers, laptop computers
and CDs or DVDs.
Understanding the policies, procedures and methods for document control that exist in an
organisation is an important part of requirements specification. This understanding is also a
Ver
precondition for the later design, review and production of documents. If requirement
specifications
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 4 of 73
also encompass a system of documentation, then the specifications may include the ways and
means used to manage documents and version control.
Manual or informal systems for recording data and records can create confusion, mistakes and
delays, as technical workers waste time searching for the information they need, or recreating
data that already exists. The key point is that information in a document, regardless of its
format or media, should be well managed.
The basic methods of document control
The simplest form of document control, especially with single sheet documents and diagrams,
is a small diagram for inclusion with all technical documents. Saving the diagram as a
template enables its inclusion, with details, on all procedures and instructions, for instance.
An organisation may have a range of information that should also be recorded. A control table
can be included at the front of longer documents, or with the master copy file, as shown in
Table 1.

Table 1: Version control table

Date Produced by Reviewer Editor Version

25/07/07 John Smith 0.1
21/08/07 Jane Gray 0.1.1
28/08/07 Vince Price 0.1.2

Configuration management
Depending on the medium, an organisation‟s policies for storage of documents will discuss where
documentation is to be kept and how it is to be accessed. That documentation may be paper-
based, on a server somewhere or backed up onto a CD. It is important the procedures for the
storage are created and adhered to, and these too may be a precondition or a part of requirements
specification.
Configuration management refers to the storage and security of documents. Table 2 below is
an example of configuration management.

Table 2: Configuration management example

Item Location Responsibility

Draft
(destroy when master copy is
available)
Master copy
Baseline digital copy
Hard copy master

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 5 of 73
 Baseline control, as shown in a template in Table 3, refers to the minimum level of support
and control for documents. Again, templates help ensure that this level of information is on
all documentation.

Table 3: Baseline control

Name Signature Date

Author
Project manager
Reviewer

Defining the scope of work

Understanding the scope of technical documentation requires answers to the following questions:
 What is the goal of documentation (in a clear and refined description)?
 What is to be achieved by technical documents?
 How is it to be achieved?
 Who would normally achieve it?
 What other resources will be needed to achieve the goal?
When you have the answer, you have a much clearer picture of what the documentation is all
about. In defining the scope of the job of creating or reviewing documents, you would:
 arrange meetings with the sponsor and all stakeholders to determine their requirements.
 clearly define the goal and objectives for the project of creating documentation, based on
the needs and expectations that you determined.

Working out what is required

From broad questions to details

To start gathering requirements you first need to ask broad questions:
 Why does the organisation need a particular document or a system for documentation?
 What exactly is missing, or not working?
 Is there a problem with the content of documents, their format, or their availability?
 What will they use the information in the documents for?

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 6 of 73
Ver
 You will also need to consider the needs that might arise as one system connects to other
systems. Is there a technical problem, a service problem or a support problem? Is the
documentation
compatible with organisation rules, and goals and policies? Is a change to documentation needed
because of government laws, or because the needs of clients aren‟t being served.
Gathering details of different, sometimes conflicting needs involves forming a clear
understanding of relationships between goals (the different reasons why), functions (what for)
and constraints (limits of scope and budget etc). You will need to understand system
behaviour, how communications are organised, the information technology, and definitions of
acceptable service.
You can now begin to work out what technical documentation is required by an organisation
by asking:
 What documents does the organisation need?
 Why doesn‟t it have them already?
 What documents exist that aren‟t necessary?
 What are the documents used for and by whom?
 What information should they include?
 What format will they have? What style will be used?
 Where is the information collected, where does it go?
 How are the documents stored?
 What will happen if you don‟t have them, or they aren‟t reliable?
Table 4 outlines and comments on types of requirements for technical documentation.

Table 4: Categories of requirements

Business Technical Functional Information

requirements requirements requirements requirement
s
Examples to Compliance, Available Common use, Accuracy,
consider for Value, technology, System Circulation,
technical Security, Existing systems, processes or Usefulness,
documentati Disaster Accessibility, performance, Copyright,
on recovery, Compatibility, Data archiving, Validation,
Reporting Environment, Audits and Content,
functions, Hosting, controls, System Format,
Interface Location administration, Deployment
functions Conversion from
one format to
Comments Documents are The platform for Can the users Does the
used for your operating capture process of
decisions and system may information that documenting
reference. The dictate what is required, store information
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 7 of 73
 business case for can manage information and support the
documents, the documents. Also, publish information
goals, and the available information as needs. Does
scope of hardware, required, and the system
documentation software, move information allow for
and sponsorship stationery, and to other domains. changing
of the project are facilities need to needs?
all be considered.
interdependent.

Collecting requirements
Before technical documentation requirements can be analysed they must first be collected.
Ideally, the collector needs to take into account every point of view and fact. The ability to do
this will depend on the time, budget and available resources. A good start would be to
interview the person who has asked you to determine the documentation requirements, to get a
clear idea of:
 what result is expected or needed
 the amount of time you have
 a budget for the project
 who will help you
 what authority you will have.
Some techniques to gather requirements include:
 inspecting the documents and their use
 interviews, workshops and use cases
 sample documents, templates and checklists.
On the internet there are many resources where you can refer to and compare sample
documentation systems. Documentation specialists use several techniques to dig below the
surface and get to the core of requirements. Some of them are briefly described here.
Start with who you know
Interviews with the client, subject expert and major stakeholders are necessary in defining the
requirements for documentation. If you are a part of a large organisation, a larger number of
individuals may need to be consulted. Prepare your questions carefully before you start
interviewing.
Ask questions of stakeholders or interview users. On a major project you may be working
with a team and can interview more widely. This will increase the time and cost of the
survey, but may reveal discrepancies.
Not everyone will be available for interview. You might send a questionnaire by email, or
explore other ways to get information you need.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 8 of 73
Workshops and use cases
Bring people together for a workshop, if possible (it may be hard to get all the experts
together at the one time). Workshops are good for canvassing the problems of documentation,
but less productive in producing solutions.
A use case draws on scenarios that describe how users will interact with the documentation, to
achieve a specific result. It is something like a role-play on paper. Use cases are good for
establishing the functional requirements of documents. A use case considers things like interface
between the users and the system.
Evaluating requirements
When asking clients, users and stakeholders what they believe a document system must have,
you can be silently asking yourself, is this requirement:

Necessary? Can the organisation meet its needs without the

technical document? If the answer is yes, the document
may not be necessary.

Supportable? Can the requirement be supported in the

documentation system? If not, the requirement should
be checked or changed.

Unambiguous? Can the requirement be interpreted in more than one way?

If yes, it‟s time for more interviews or editing.

Complete? Is there anything missing? Better to have

stakeholders review the specifications now, than have
problems later.

Dependable? Are there conflicts with any other requirement, or

other parts of the system?

Concise? Is the requirement simple, short and to the point?

Acknowledged? Is the source of the requirement documented? Are

reviews cross referred to the source for a double check?

Identified? Can other people readily find and identify this

requirement, in case of later need for amendment?

Reviewing requirements to come up with specifications

Once you‟ve heard what every one believes they need from the documentation, you must analyse the
data.
First, break requests into distinct requirements. If one person proposes that a document must do „A‟
and „B‟, each proposition must stand alone, so that it can be accepted or rejected on its merits.
Look for unanswered questions, and find the answers, from one source or another.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 9 of 73
If there is a vague requirement, such as a document should be „short‟, you should go back to the
source, and ask exactly what that means, and why it is important. Don‟t assume that you know.
Find out what a „long‟ document is.
Combine those requirements that are similar. Categorise them into their system properties,
such as function, form, style, content, etc.
Identify contradictions, and ask the sources to explain.
Prioritise the requirements. There are core requirements, such as features which if missed will
affect the rest of the system. There are requirements that must be included and those that are
optional.
Once you have an ordered and integrated list of needs and recommendations, you should ask the
participants to review your interpretation of their requirements. This document is really the basis
for the first draft of the requirements specifications.
Validating requirements
It is not unusual or unrealistic to expect that not every one will agree with the requirements
specifications that are proposed. There may need to be some resolution procedure in place, if
negotiations don‟t lead to consensus. The final word belongs with the client, or project sponsor,
to resolve issues and make final decisions.
Submit a draft of your specifications to select users. Ask them for feedback. Can they comply
with these specifications when they create documents? Ask them to create or amend a
document using these rules.
When others use documents created to these specifications, will their work benefit from them or
be constrained?
If you‟ve used a reiterative process in forming your recommendations (by circulating drafts,
for instance), and kept participants informed of your reasons, then you should not have too
much trouble getting consensus.
OVERVIEW OF SCOPE OF WORK

A scope of work sets forth requirements for performance of work to achieve project objectives.
The scope of work must be clear,

accurate and complete. SOWs have to be read and interpreted by persons of varied
backgrounds, including performing contractors

and their suppliers, project managers representing departments or offices, and the
contracting officer. Therefore, the SOW should be

worded to make more than one interpretation virtually impossible.

Developing a scope of work presents unique problems, because each SOW is designed for a
unique procurement action. A normal

procurement specification, such as a purchase or supply contract, is used to procure

standard products and repeatedly used services.
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 10 of 73
But a scope of work is mainly used to procure a variety of nonstandard services, as
well as development of software and hardware,

and construction. Thus, no uniform SOW format can be applied, but guidelines can be followed
to achieve an end product that meets

the specific objectives of the contract.

The difficult and sometimes controversial function of proposal evaluation and source
selection is based largely on a scope of work,

which is the baseline standard for evaluating all proposals, for reconciling them to design or
other requirements, and for determining

the best approach to competition. Evaluation criteria are based on a scope of work that
defines project objectives and requirements

for their achievement. Challenges to the proposal evaluation and source selection are almost
always traceable to an uninformative or

ambiguous scope of work.

Any scope of work must cover the following points:

o What needs to be done

o Who will do what

o When it should be done

o Where it should be

done

o How contract performance will be judged

The scope of work may also define how the job is to be accomplished. When objectives are not
well described and defined, misunderstandings are likely. Ambiguous SOWs can lead to
unsatisfactory performance, delays, litigation, and high costs. (Section D

deals with specific SOW

language.) Scope of Work Format

Although the elements of a scope of work can vary with the objective, complexity, size and
nature of the work to be performed, a

flexible, seven-part format provides a practical approach to document drafting. The suggested
seven parts are:
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 11 of 73
 I. Background

II. Scope

III. References

IV. Requirements include schedules

V. Progress/Compliance

VI. Transmittal/Delivery/Accessibility

VII. Notes

Summary
In this reading, while keeping in mind the attributes of good documentation, you focused on
investigating the goals and needs of an organisation to determine its requirements for technical
documentation. The importance of document control for later processes of design and
production was discussed. The basics and importance of determining document scope and
having requirements specifications validated, was also outlined.
Progress
Have a look at the next section—Activity. If you have trouble, review this reading or perhaps
take a look at some of the listed Resources.
When you feel ready, try the Self check section at the end of this topic. This will help you
decide if you are now able to complete the task and attempt assessment.

Design technical documentation

Inside this reading

What is the technical information required to do? 15

Audience, purpose and function 16

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 12 of 73
Ver
 Style documents 18
Style guides and manuals 18

The use of templates 22

Formatting and templates 23

Structure and navigation 25

Principles of structure 25
Presenting different types of information 28

Digital document design 31

Online and onscreen publishing 32
Interactive aspects of design 33

Copyright basics 37
What is protected by copyright? 38
Granting and seeking copyright permission 39

Summary 40
Progress 41

What is the technical information required to do?

Figure 1 below helps you to map the process of creating technical documentation, where
requirements and standards help pre-determine the design. Having already asked what is
required of the technical documentation, the design phase begins by asking a range of
questions so to understand what the technical information is required to do.

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 13 of 73
Ver
 Figure 1: The place of design in creating technical
documentation

In the area of IT there are many different types of technical documents, including documentation
for computer systems, software development, web sites and a broad range of organisational projects.
If complex technical documents are to make sense, and be useful, the design needs to start
with careful planning.

Technical information is often practical, mechanical and procedural. The information content
in a technical document can include:
 data  measurement
s
 analysis  statistics
 instructions  designs
 reviews  reports
 records  discussion.

A good technical
document:
 meets a need
 serves an audience
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 14 of 73
  is easily navigated.
All effective technical writing should
be:
 technically accurate
 complete (nothing necessary has been assumed)
 have no more content than necessary
 focused on a single issue
 easy to understand
 logical, consistent throughout and well organised
 appropriate to the organisation and for the user.
Audience, purpose and function
Before you start designing a document you must know (or make assumptions
about):
 who will use the documents
 what they will use the documents for, and how they will use the documents
 what they are expected to do with the information in the document
 if they will read the entire document, or just the parts they need quickly
 if they need access to technical information for quick reference.
Your reasons for documentation will affect your design. For example, you may be
documenting procedures and policies for quality control.
The design of technical documents includes deliberate choice
of:
 genre (what type of information?)
 function (how will the information be used?)
 structure (how the information is made accessible?)
 content (what level or depth of understanding you will provide; if the publication or
product is for beginners or experts, for building or for maintenance)
 format (how it will it be published, as a book, paper, file or web site)
 style (including the use of illustrations, text, data and language)
 tone (will it be intended as a reference or explanatory object).
Content distribution—what goes
where
You may consider a system of publications, with both sequential and selective
access.
Experts in a company may need technical documents for reference, for instance, and need to
Ver
find a particular fact directly, or a measurement in the middle of pages of other specifications.
 They don‟t need to read the whole history of the product. For maintenance, a technician needs to
find a

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 15 of 73
procedure quickly, without all the solutions to other problems. They need to access
information selectively. A new employee however, might need to read more; they need to
know about the product, and the processes, and the reasons. The learner may need to read
sequentially.
In designing documentation to distribute the content across different documents, you need to
decide how the content of each publication might overlap. For example, a note about the speed
of a hard drive in hot weather might also appear as a footnote in a training manual.
Other considerations
Depending on your role, you may also consider the following issues as you design your
technical documentation:
 Publisher: Who is in charge of ensuring this publication meets its goals and
reaches its audience needs?
 Author: Who will write or provide the content for this publication?
 Rank: How does this publication rate in relative importance to others that you have
to produce?
 Functionality: What functions will be built in (especially if it is online, for instance, the
use of form fields, java script).

Style documents
Style can refer to the way a writer organises sentences. A good style for technical writing is
succinct (using only as many words as needed), clear (having no ambiguities of meaning) and
precise (grammatically correct and always choosing the simpler and more direct form of
sentences and paragraphs).
Style also concerns typography or design; how a feature is placed, or is styled. The different
features of a template for instance might be called „styles‟; heading styles, styles for body text, etc.
A certain style is used at certain times. In templates, those formats are then recorded on a style
sheet.
Style is also the set of publication conventions, such as whether book and movie titles should
be written in italics; expression of dates and numbers; how references should be cited. The
document that is kept as a record of conventions used for a particular document is also called a
style sheet.
Style guides and manuals
Style guides are often written for particular organisations or publishing houses (to specify a „house‟
style). Rules of style can include consistency in the use of typography, layout, word choice,
spelling and punctuation. Style guides list all manner of conventions to be used to adhere to a
corporate image and a consistent way of producing and presenting documentation.
Style manuals generally have much more comprehensive information, such as detailed advice
on publishing in both print and electronic formats; or information on the general practices in
editing, design, electronic publishing, indexing and printing fields, for instance. Style guides
often contain three types of information:
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 16 of 73
1 Process (how things are done, for example, how to create a document and get it approved
for publication)
2 Design (documents appearance to conform to the business image)
3 Style (the house style, and if there is a template to use).
Keys to the creation and maintenance of a successful style guide include:
 an effective requirements process, in gathering
information
 a keen team of stakeholders and ways set for the guide to evolve.
A style guide has rules and suggestions or recommendations to be followed when producing a
document. Style guides help ensure consistency in presentation (titles, headings, sub-headings,
etc), vocabulary, style and layout. What should be rules (that are non-negotiable) and what
should be suggestions depends on organisational policy. Thus, the rules will vary from one
organisation to the next.
Style guides are regularly updated to reflect current business needs and policies, as well as
changes in style over time. They are then circulated to all who may be affected by the changes.
Style guides are often accessed on a company‟s intranet site where the digital copy can be easily
kept up-to-date.
Style guides usually apply to all documentation or in some cases a guide might exist for
technical documents. The style guide should contain design decisions that directly affect
writing and editing, for example:
 the conventions to be used on chapter and section and page numbering
 heading styles; titles for figures and tables; the layout of vertical lists
 the rules for highlighting text (bold, underline or italics)
 which template is to be used for which type of document
 which version of English to use (Australian, American or British)
 which system of measurement to use, if not metric, and specifying any variations (for
example, „dots per inch‟ in a metric guide)
 mandatory reference materials like an industry style guide, a particular dictionary, the
company‟s design and process guides
 which elements such as title page, preface, table of contents, glossary, index, copyright
details are required, and what to include in them
 where headers and footers appear and what they should contain
 when to spell out numbers and when to use numerals as well as defining the punctuation
to be used in numbers over 999.
 writing style, level of language usage
 any special requirements or any terms that should be avoided.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 17 of 73
 Style sheets for documents
Style sheets for are referenced to style guides and record all decisions made for a
particular document. A style sheet may record:
 how a word is spelt, hyphenated or capitalised when several versions are common or correct
 conventions for typography, font usage such as typefaces and sizes and use of borders
 any deviations from standard punctuation, spelling or usage
 if figures are centred or flush left, on the page or within the column
 page size and margins, number of columns, offset style (if used)
 bullet characters, including whether and when to use non-standard bullet styles or more
than one bullet style
 if list numbers in procedures have a period after the number
 use of horizontal and vertical rules in tables of data.
An organisation might keep style sheets for individual documents. When another person works
on a document, they have a record of spellings and usage, as shown in Table 1.

Table 1: Style sheet example—usage and spellings for IT document

General
Lists: no „and‟ at end of penultimate points; no semicolons
Tables: initial capital for each item in each column; column headings ranged
left Punctuation: single „smart‟ quotes most subjects except program language
text where single and double quotes using „primes‟ are kept.
ABC DEF GHI
backup (n/adj) checksum help desk
backed- up (verb) desk HTTPs host ID (two
CD-ROM check parts)
coordinate dial-up ID (no need to spell-
copyfree downtime out)
copyleft flow chart ipconfig and
ipconfig/all (lower case)
JKL MNO PQR
loopback (n/adj) NetBIOS read-me (files/docs)
loop back (verb) net ID (two parts) re-use
onscreen pseudopodia
practise (verb/transitive)
practice
(noun/adjectival)

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 18 of 73
Ver
STU VWX
subnet and web
subnetting sub-layer web site (two
time frame (two words) words) workstation
time line (two words) walkthroughs (one
word)

References for usage in Australian Government Information Office Style

Manual for Authors, Editors and Printers (6th edition), published by
John Wiley and Sons, Australia and on the web at
http://www.agimo.gov.au/information/publishing/style_manual; and an
online style guide from the Institute of Electrical and Electronics
Engineers Computer Society, the IEEE computer society style guide, at
http://www.computer.org/author/style and the Macquarie Dictionary, on
the web at http://www.macquariedictionary.com.au
The advantages of using a style guide
Style guides used together with templates (discussed next) can:
 enable consistency within documents and allow a consistent presentation of
information across all business units
 create a familiar „tone‟ so that published documents conform to the business image and policy,
including legal
requirements
 provide a common vocabulary
 provide an orientation or training aid for new employees or new members of a
production team
 define which style issues are negotiable and which are not
 remove the repetition of the decision-making process in the reproduction of
common elements.

The use of templates

Templates are documents, much like a stencil or a model, which can be used over and over
again without changing the original. Templates are a special type of document that can hold
text, styles, macros, keyboard shortcuts, custom toolbars and AutoText entries.
A document created using a template will have access to all of these features added when the
document was created, saving the user the work of setting up, formatting and adding features.
All the user needs to do is add the content.
Most applications include forms for the most used documents as templates. Many web site
managers who are not programmers, or use mark-up languages like XML and HTML, use
templates.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 19 of 73
 Advantages of using templates
A template saves the experts who must write or draw content for publications from the work of
designing and formatting every document individually themselves. Instead, they can
concentrate on the quality of the information.
Templates that conform to the style guide and style sheets have the advantages of:
 prompting the user to include all relevant information
 creating a document in an acceptable format or layout
 creating consistent documentation across the organisation
 facilitating the handover of projects in the event of personnel or organisational changes
 saving time and potentially costs to create documents
 reducing trial and error and ensuring greater accuracy
 reproducing a design and functionality that is already tested and proven.
Formatting and templates
Format refers to the properties, particularly visible properties, of a document. For example,
word processing applications allow you to format text, which involves specifying the font,
alignment, margins, and other properties. Format and typography help make the structure and
progression of documents more easily understood.
Two very different rules that apply to document formatting are that:
1 The format must be consistent; the appearance of content should be uniform from one
document to another, so that the parts and elements work the same way for the user (and
the writer and subsequent reviewers and editors).
2 The content is not wholly dependant on the format, so that you can re-use or convert
the content to different media—such as a web site or a manual.
Some decisions related to the format of your document include:
 Files: do you deliver the document as a single file, or will it be many files? This
applies to web documents and longer publications.
 Style sheets: What automatic styling have you set up in the application you are using
the make the documents, to ensure formatting is consistent?
Templates are also an important part of the design of technical documentation, since (if used
correctly) they allow for the automatic and consistent styling of structural items and features,
such as:
 different heading levels
 text types for body text, extracts, footnotes and references
 text features such as lists
 other features such as marginalia and equations

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 20 of 73
Ver
  automatic table of contents generation.
An organisation may have a general template for technical documents (whether traditional
documents or web pages, designed so that one converts to the other), or they may have different
templates for different purposes. The templates used will usually also support and reflect a
particular corporate or business image.
Good web page design uses style sheets called cascading style sheets (CSS). A cascading style
sheet allows one style guide to apply formatting automatically to all the pages and content in
the web site.
Templates for different parts of a process
Templates help work out some design issues in advance so that documents follow general
principles. Many organisations provide writers of technical documentation with templates that
also include advice and notes about structuring material and how much information is required in
what places.
The structure of documents needs to be especially clear and logical and templates can help
ensure that written material from experts needs less work before it is subject to editing and
review.
Other templates (without the writers‟ template instructions, etc) might then be used for further work
on documentation to prepare it for publication.
A guide or instructions for using templates—explaining functions of all the different features
and how to apply or use them—is often a part of an organisational style guide.

Structure and navigation

Principles of structure
Structure is important to help readers understand the content of a document. Structure is
especially important for technical documentation, where information is best organised into
chunks. With more and more documents available in electronic form, onscreen (online or on
CDs of DVDs) and connected through hypertext, decisions about structure become even more
complex. Yet fear not, some easy to understand principles of logic in organising material remain.
The structure of a document helps place emphasis on content where emphasis is needed,
and it arranges the order of information by importance or by necessary progression or
sequence (for procedures and instructions, etc), or both.
When designing the content of technical documents, your aim is to break complex information
into its most basic elements and then present those elements to readers in such a way that they
can quickly and easily scan and retrieve the information they need.
Give your readers the option of reading to the level of detail they need. If the users of your
document are experts, they want to go straight to a particular fact, or instruction. An expert may
not need to read the whole document. Don‟t force them to sift through detail in order to find the
main point. Important details need to be where they can be found if needed.
The flow of information
The most basic way of organising information is by a hierarchy of importance, using a
Ver
hierarchy (or labels) with the higher level having a larger font). Hierarchical presentation begins
at the top level,
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 21 of 73
 which is general, such as an introduction. Like an upside down tree branching (or like tree roots),
the information works toward the lowest level, which is more specific and detailed.
With three heading levels, for instance, you would:
1 begin with an overview of the entire topic under a level 1 heading
2 identify each block of information with a lesser, level 2 heading
3 describe each block in detail, one at a time, under level 3 headings.
Headings (or titles or captions or information labels) should always be descriptive, specific and
informative. They tell a reader or user for what to expect in this block of information and help
them to find specific information quickly, and if necessary, in isolation.
Each block of information may in turn consist of smaller parts, organised around a single
subject and having one clear purpose, and expressed in paragraphs, each of which develops a
single idea in two or three sentences (or as many as are needed to cover the idea).
Mapping information

Search and reference features

In technical documentation, listing contents for easy access and reference is also needed, which
can include the features in Table 2.

Table 2: Document components and features that aid reference and use

Tables of contents A table of contents lists and reflects the hierarchy

of main and minor headings in a document.
Indexes An index has keywords, terms or names that are
essential for users to find a subject or detail, or for
people seeking that information, to find your
document on the web. On the web, even if your
document is only a few pages, you may need about
50 key words to help search engines find it.
Glossaries Glossaries can include key terms, specialist terms
or terms likely to be new to readers or users of the
document; glossaries can also include a list that
spells out acronyms used.
Cross references In print documentation cross-references might include
and hyperlinks page numbers, and for digital documents hyperlinks
can perform this function in addition to providing
links to other documents.
Full text search For documentation on web pages a search facility
might be designed to aid use and access to topics and
sub- topics by users.
Structural You should arrange the structure of different
consistency technical documents within an organisation the
same; users then
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 22 of 73
Ver
 across documents quickly know how to use that document.
Integrated Graphics help interaction with readers and users.
graphics Integrated graphics (often charts or drawings) are
those placed near text that relates to them (instead of
having them off in another part of the document, such
as in an appendix).

Structural ordering of traditional and longer documents

The structure of longer documents needs even more detail to help users find the information
they need. Broadly, with larger documents, information can be divided into the three-parts of
front matter, body matter and end matter.
Front matter
Front matter is organised according to what makes best sense for the use of documentation.
Some of the common features of upfront material in documentation can include:
 title page stating what the document is about, and the revision level, such as version 1.0
 copyright statements standard for all documents
 notes of revision level, stating the history of document revisions
 configuration management tables which would show where the original copy of the
document is kept, where a hard copy is available and where on the network server to
find a soft copy
 baseline control tables, which is used by the document writer, the project manager and
the subject expert to sign-off on the document
 tables of contents, which can be produced and updated automatically in word
processing applications
 prefaces, which are often an introduction, kept to one page and are a summary of the
document‟s contents (an executive summary or an abstract can sometimes be used
with longer documents).
Body matter
The body of the document is its substance. It is the content, ordered into parts or sections of
chapters (or some combination, depending on the length or page extent of the documentation).
In print material, headings within the body of the document would be listed on a table of
contents and these would be hyperlinked in online or digital versions.
The principles of a structure discussed above apply to the body of the document (having it
ordered under a hierarchy of headings and with a logical progression), which then can include a
range of media for information and data, diagrams, tables and graphs.
Appendices are often part of the body of a document in technical documents (though they can
also be treated as end matter) and include tables, or raw data or other sets of technical
information that support explanations or procedures in the text.

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 23 of 73
Ver
 End matter
End matter (as mentioned) can include appendices and attachments that support of explain
subjects in the body of the document. A glossary of terms can also be placed in end matter, for
readers unfamiliar with or new to technical words in the document, and to explain acronyms
used. If the document is long enough, a separate list of acronyms might be included.
An index is standard for all long documents; word processing applications can help the writer
sort information for an index, although often, especially when documents are typeset in page
layout programs, the index is created when the pages are final, and is done by specialist
indexers. Indexes on web sites serve a different purpose of people being able to find your
document online from a range of terms.
Presenting different types of information
Writers learn that once they have classified their information, questions of presentation (in what
way or form should it be presented?) start to appear. Table 3 shows some established ways of
presenting information types.

Table 3: Some established ways of presenting different types of information

Information type Best presentation method

Classifications Lists and tables
Structures Charts and drawings
Procedures and instructions Action tables (concise, sequentially numbered instructions,
each beginning with an action word) and flow charts

Using flow charts

Flow charts are often used to illustrate documents for procedures and work instructions
because they force the reader to think in terms of simple elements or steps. Procedures are
visualised more quickly than in text descriptions, which makes flow charts a faster way to
present and to assimilate information.
Flow charts are also easier for quality engineers, employees and auditors to understand.
Technicians and engineers can map out procedures quickly and review them for accuracy before
completing more detailed documentation.
A simple draw toolbar in word processing applications can help produce flow charts. Table 4
shows commonly used symbols.

TTLM Development Manual Level III

Ver
Competency Title Create Technical Documentation Page 24 of 73
Table 4: Commonly used flow chart symbols

Beginning step Decision choice

Process Inspection

Decision point Ending point

Document Preparation

Using graphics
Technical readers are in many ways visually literate; visual elements are a part of learning
technical subjects and are expected in technical documentation.
Text alone is not enough in complex technical documents to make meanings clear, and even in
basic documents illustrative material can include a range of graphics. Intelligent use of good
quality graphics is important to the design of technical documents.
Graphics help achieve documents that can be used for quick reference. Graphics are easier to
remember than words and can be aids to memory—they also help people with reading, language
and vision difficulties. The use of graphics can also cater to readers and users with different
learning styles.
Avoiding bad graphics
In many technical documents the best on graphics offer are poor quality and inappropriate
screen shots. Reasons for bad graphics range from editors not wanting to spend money for a
graphic artist or photographer as well as a writer, or fear of copyright breaches (easily
committed with graphics).
Many documents use graphics poorly. Graphics are often distorted to fit an available space,
rather than be given a space of their own. The text is often separated from the illustration and
few document managers have any training in illustration.
Finding the right balance
On the web the reverse occurs, with an artist or designer creating great graphics where the
associated text is poor. A balance between words and images is necessary for good
communication; quality graphics can lessen the need for text, and yet the text then used needs to
be precise, concise and well expressed.
It becomes especially important that graphics used on web pages are such that an international
audience can relate to and understand them. Use of line illustrations, photographs and screen
shots are effective only when they are understood and convey the proper meaning. Always
consider how readers of different cultures will interpret colours and symbols, etc.
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 25 of 73
Digital document design
Both print and onscreen publishing and later replication to CD or DVD format, or to other
portable media, are almost exclusively digital processes.
The reproduction of technical documentation is also increasingly digital. Manuals and printed
materials can be published to support material onscreen in portable media and online via the
web. It is also possible for a combination of portable media and online publication. When more
than one medium is used for the same documentation, some basic principles are that:
 the content of documentation should be able to be converted from one media to another
 allowance needs to be made for onscreen materials to be printed
 the relationship should be clear between print and onscreen materials.
Online and onscreen publishing
Technical documentation is increasingly published on intranet or web sites, or on portable
media, such as CDS of DVDs, to provide onscreen access and the ability to interact with
information.
Internet or onscreen access also works well where technicians and other practical users travel
widely and are that way saved from lugging heavy reference documents. In some cases where
technical information is published onscreen, it may be to the detriment of printed documentation
(with less information being printed). Onscreen publication may also supplement or update
printed technical documentation.
The most basic way of presenting technical documentation online is by material grouped
under headings that are hyperlinked from menus.
Print materials online
It is also common for print materials to be available for download from web sites for users to
print or to read on screen. If layout is important for documents, web pages can be counter-
productive. There may be no guarantee, for instance, that the viewer will see the document as
you intended. Downloadable documents are often made available as specialist information on
web sites, with navigation among HTML pages used to support broader technical information.
PDF files
Portable Document Format (PDF) files, generated by Adobe Acrobat software, are intended
for brochures, magazines, forms, reports and other materials with complex visual elements,
which will be printed on PostScript printers. They are the most common format for
downloadable files. The format was created to remove machine and platform dependence for
the documents, and its goals include design fidelity and typographic control. It also functions
for online reading to some degree (with hyperlinked contents lists). Many word processors,
page layout and desk-top publishing programs can easily create PDF files; hence many web
sites now make PDF technical documents accessible for download.
Conversion from print to screen
Converting printed technical documentation for onscreen use involves the following steps:

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 26 of 73
  Gathering material (identifying and assembling all the individual components of
the publication)
 Developing the architecture (explained in general terms below)
 Developing access schemes (explained below)
 Developing the navigation tools (the features of the print document can be refashioned
into navigation bars of consoles)
 Constructing the content (the style and structure of the content will be adapted to the
way that readers search, scan and absorb onscreen information, and converted to a file
type such as HTML or PDF)
 Showing relationships between printed and onscreen formats (keeping a visual
connection between printed and online version of documents is important, the tile page
of cover of the printed materials, for instance might be the basis of the opening screen).
Interactive aspects of design
Technical documentation evolves as technology changes. While the development and production
of documents have times for review and user testing (for both print and onscreen media),
reproduction onscreen means that feedback can be more direct. Users can more directly
influence both use and design, by for instance, providing the user with diagnostic tools.
The most sophisticated forms of technical documentation include web-enabled Interactive
Electronic Technical Manuals (IETMs), which are a digital package of information required
for diagnosis and maintenance of military and commercial equipment (including complex
weapon systems), and Interactive Electronic Technical Publications (IETPs) that support
complex systems and equipment.
Information architecture
The basic principles of structure for documents (breaking information down using mapping
aids, contents lists, headings, graphics and visual elements, especially typography) still apply to
the ordering of information and access schemes on web sites. Yet the „linear‟ aspects of structure
(such as the three-parts of front, body and end matter), no longer apply.
Information sits on different levels of a web site or onscreen hypermedia document, hence the
metaphor often used of „drilling down‟ from basic to more complex information.
Technical documentation onscreen can also feature multimedia, with DVDs able to incorporate
video graphics. As digital video technology and streaming/download speeds continue to
improve, video in technical documentation is bound to rapidly grow. (One of the common
software tools for video documentation is briefly explained, with a link for reference, in
Resources).
Documentation in a range of media may exist across and between a series of screens and pop-
ups on a web site, at different levels. The design or architecture of the site will determine the
pathways and links by which that information is found, where it is placed and how it is
displayed.
Web documents have greater potential for interactivity and a longer shelf life if they are
continually updated and changed. Yet web users are looking for quick, brief information, and
not all types of
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 27 of 73
technical documentation may be best presented this way, without recourse to more traditional forms
(such as also having PDF files etc, at that lower level).
The principles of good writing do not change when material is on the web or onscreen (contrary
to the impression that so many badly written and unedited web sites might give you). The only
difference may be the extent to which material is broken down into small „scrollable‟ sections or
screens, with relatively short sentences, which is a form already suited to technical
documentation.
When creating a web document, content and structure are emphasised by means of the
information architecture of the site, not simply by the layout of individual pages. Yet the
principle of having all documentation conform to the same broad structure, using the same
styles, applies also to web sites. Navigational design needs to be consistent on all parts and pages
of the site, and on all levels at which materials are placed.
Access schemes
Access schemes are the ways of displaying content in an order or sequence that is logical for the
content and which also accounts for the approaches likely to be taken by different users of
technical documentation.
Things such as tables of contents and indexes can be converted to become access schemes
online. A site map on a web site, for instance, describes aspects of the information architecture
that users need to understand, and works much the same way as a table of contents does in print
materials.
Two types of access schemes are exact access schemes and ambiguous access schemes.
Exact access schemes
Exact access schemes can provide access to material in categories arranged:

alphabetically
 chronologically
 sequentially
 geographically.
It is more likely that documents concerned with procedures, such as instruction manuals, will be
arranged sequentially. This is a common approach for technical documentation design, and it
can be supplemented by ambiguous access.
Ambiguous access schemes
This type of access is also common for technical documentation, particularly when
documentation is extensive. Such schemes are termed „ambiguous‟ because the way the headings
and material for a subject, topic or process is organised by the writer or publisher might be very
different from the way in which a reader will search for it. While a manual might specify the
logical sequence of events to build a system, for instance, a technician using the documentation
might need information on just one element, and is unsure of the stage at which that element is
discussed. If the different ways a reader might search are carefully thought about in the design,
this type of access can be more useful.
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 28 of 73
Metadata
The information architecture of a web site needs to account of all the facets of technical
documentation so far discussed. There are also potentially much more complex structures
across and between pieces of information. These structures must also be designed to be
consistent and easily used.
Metadata is information about a document‟s design and contents—literally „data about data‟. An
example of metadata for print materials is a library catalogue card, which contains data about
the nature and location of a book: It is data about the data in the book referred to by the card,
hence
„meta‟ data. Metadata describes:
1 Content, which relates what the object contains or is about
2 Context, indicating who, what, why, where, how aspects associated with the object‟s creation
3 Structure, such as length, fields, and columns.
As an example, MP3 music files on the Internet have metadata, to help searchers find the music they
want. Internet documents aren‟t always so neatly catalogued, as might be seen in Figure 1.

Figure 2: Sample of document metadata on the Internet

Figure 2 is an example from a HTML document and shows the use of the „Dublin Core‟ (DC)
metadata standard. It outlines both content and context information.
Metadata can significantly increase the „discoverability‟ of documents and information in an
environment like the web, where users search for information rather than accessing a defined
navigation system. As an example, search engines rely heavily on metadata provided as „keywords‟ in
a web page.
While there is a wealth of information in documents on the Internet, or accessed via
organisational intranets, information about each document is often missing, such as that for
labelling, cataloguing and description, structured in such a way that allows document pages to
be properly searched and processed by a computer user. An absence of metadata can restrict
the usefulness of online publishing of technical documentation.

Copyright basics
Copyright is the exclusive right of the creator of material to reproduce, adapt, publish, perform
and communicate that material. Copyright can be thought of as a bundle of rights that can be
traded by the copyright owner. Copyright is designed to reward and provide incentives to
creators of copyright material.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 29 of 73
When you are designing technical documentation you should allow for any copyright
requirements. Many organisations have copyright rules. In larger organisations there is often a
whole department responsible for copyright.
Two issues about copyright for you to consider are:
 the copyright that you or your organisation might own over information in
technical documents that you have created
 your obligations when you need to use information produced by other organisations
or creators.
The Australian Copyright Act 1968
Copyright is granted by law in Australia by the Australian Copyright Act 1968 (Act). Copyright
protection is immediate and automatic once a copyright work is created. The work is then
generally protected by copyright law for the life of the author and a further 70 years.
There is no official register for copyright. It is an unregistered right (unlike patents, registered
designs or trade marks). There is no official action to take, (no application to make, forms to
fill in
or fees to pay). Copyright comes into effect immediately, as soon as something that can be
protected is created and „fixed‟ in some way, for example, on paper, on film, via sound recording, or
as an electronic record on the Internet.
The creator of a copyright work is usually, but not always, the first owner of copyright in that
work. The copyright in any material you produce in the course of your employment will be
owned by your employer. If you are contracted to produce technical documentation for an
organisation, for instance, the contract will often state that the organisation owns or is assigned
copyright in any material you create for that documentation.
It is a good idea for you to mark your copyright work with a copyright symbol © followed by
your own or you organisation‟s name and the date, to warn others against copying, but it is not
legally necessary.
What is protected by copyright?
The Copyright Act 1968 gives protection to two broad categories of material—„works‟ and
„subject matter other than works‟. Works are further divided into textual (literary and including
computer programs), dramatic, artistic and musical works. Material described by the
cumbersome phrase
„subject matter other than works,‟ includes cinematograph films, sound recordings and broadcasts.
As you can see in Table 4, a broad range of materials can be subject to copyright. Technical
documentation might include reports and computer programs, drawings, diagrams, photos and
maps (under „works‟), and in materials in the form of film, video, DVDs, Flash animations, CDs,
audio tapes and books (under „subject matter other than works‟).

Table 4: Types of materials protected by copyright

Works Examples Subject Examples

matter other
than works
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 30 of 73
Literary novels, poems, song Cinematograp films,
lyrics, newspaper and h films videos,
journal articles, DVDs, Flash
essays, reports, animations
computer programs
Dramatic screenplays, stage Sound CDs, audio
plays, choreography recordings cassettes
Musical songs, music as Broadcasts television
distinct from lyrics or and radio
recording of music broadcasts
Artistic paintings, drawings, Published books,
diagrams, cartoons, editions magazines,
photos, maps, newspaper
sculpture s
What copyright doesn’t protect
Copyright doesn‟t protect intangible things such as ideas or concepts—only the material
expressions of those ideas or concepts.
Ideas, information, styles and techniques can‟t be copyright. Names, addresses, titles and slogans
are generally regarded as being too small or unoriginal to be protected as copyright works.
People and images of people can also not be protected by copyright.
The public domain
Public domain works are also free of copyright. The public domain is made up of the body of
knowledge and innovation (especially creative works such as writing, art, music, and
inventions) in relation to which no one can establish or keep proprietary interests (holding
licenses) or ownership. Public domain materials are considered to be part of the common
cultural and intellectual heritage of humanity, which in general anyone may use or exploit.
Works are in the public domain when copyright expires.
Copyfree and copyleft
The term copyfree is used informally when on object is free from copyright protections, and may
be copied, changed or distributed freely. For technical documentation copyleft describes a group
of licenses applied to works such as software and documents. A copyleft license uses copyright
law to ensure that every person who receives a copy or derived version of a work, can use,
modify, and also redistribute both the work and derived versions of the work. Authors want
copyleft to apply to their work when they wish to encourage and invite a wide range of people to
make ongoing
improvements and elaborations to the work. Copyleft is one of the key features distinguishing
several types of open source software licenses.
Granting and seeking copyright permission
As a copyright owner you also have the exclusive right to authorise others to use your
copyright material in ways protected by copyright. As a professional author or creator you
may choose to do this through an agency such as the Copyright Agency Limited in Australia.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 31 of 73
Using the work of others
On the other hand, if you use copyright material in any way that is protected by copyright, you
must seek the permission of the copyright owner, explaining exactly how the material will be
used and what acknowledgement of it use will accompany the material.
Fair dealing, educational and non-commercial use
There are no general exemptions from copyright law for non-profit organisations or for
personal use.
The Copyright Act 1968 (Act) does permit a degree of use of copyright works without the
need of formal permission or payment, but with a requirement that the source of the material
is properly acknowledged. Uses permitted under the Act include any „fair dealing‟ for the
purposes of study, research, criticism or review (such as quotes or extracts, etc).
Educational use and non-commercial use
Under the Act, some copying for educational purposes is also permitted if the institution has
license arrangements with the Copyright Agency Limited.
Most institutions holding archives of images allow students or individuals to use images for
study of personal use (in files downloaded) if the source of the image is properly acknowledged.
Formal copyright permission and the payment of user fees are required for any commercial use
of images.
A note of caution
The information here is only general—if you have concerns about legal issues or practices
with copyright, you should consult a legal advisor.

Summary
In this reading you have had an opportunity to discover the essentials of good document design
to support technical work. You‟ve learned that content needs careful planning of structure, style
and format. A clear understanding is needed of the reader‟s point-of-view and the uses to which
the documentation is put, as a guide, manual or reference work for a subject or project.
You will now have some understanding of how the means of delivering materials to users will
affect design for both print and onscreen materials, including considerations for converting from
print to screen.
The benefits of style guides, templates, graphics and metadata were also introduced, as were
the basics of copyright requirements.
Progress
Have a look at the next section—Activity. If you have trouble, review this reading or perhaps
take a look at some of the listed Resources.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 32 of 73
 When you feel ready, try the Self check section at the end of this topic. This will help you
decide if you are now able to complete the task and attempt assessment.

Produce technical documentation

Inside this reading

Technical communication
The need for technical documents
IT technical writers

Gathering information
Creating content

Writing skills
Preparing to write your document
Using plain English

Editing and proof reading stages

Technical review Editing
stages and tasks The
focus of editing tasks
Proofreading
Marking up documents
Proofreading tips, peer editing and computer tools

Summary
Progress

Overview

Design is an integral part of any document and can improve or impair the reader's ability to find
and comprehend information. In this module, we'll explore the different elements of document
design and how to incorporate them into an effective, consistent layout that enhances readability
and usability.

VerManual Level III

TTLM Development Competency Title Create Technical Documentation Page 33 of 73
Technical information is communicated visually through graphics. We'll look in this module at
the different types of graphics, factors for selecting graphics, and integrating text and graphics.

In a technical environment, we encounter situations in which we must explain to others how to

do something, how an object is put together, or what happens during an activity. These situations
call for special types of technical writing, instructions and technical descriptions. Instructions tell
readers how to perform a task. Technical descriptions explain to readers how an object is
assembled and operates or what happens in a process. We'll examine these types of technical
writing in this module.

Objectives

After completing this module, you should be able to:

 design documents that serve their purpose and that are appropriate for the audience
 describe the design elements that contribute to a pleasing, clear, usable document
 identify various types of graphics appropriate for technical documents
 integrate text and graphics effectively into a unified presentation
 plan and write effective instructions that allow readers to complete an activity
 develop clearly separated procedural steps that are logically organized, that are written
in the imperative mood, and that follow a parallel, sequential structure
 describe an object or explain a process using the appropriate level of technical
detail, definitions, and partitioning that is effective for the audience and the
purpose

Commentary

Designing Documents

We are surrounded by visual images vying for our attention. We are usually drawn to items
with colorful packaging and visual appeal. The visual appeal of a document—its use of color,
its title, its use of type fonts and sizes, and so on—invite us to take a closer look. The design of
a document— the arrangement of its visual elements—encourages readers to examine the
document more thoroughly and helps them find and comprehend information quickly and
easily. Effective document design is of particular value in enhancing the readability and
usability of technical documents. It guides readers to the information they need, emphasizes
important information, and projects a positive image, thus reinforcing the message of the text.

Your document design should meet your purpose and your audience's needs. For instance, you
can direct your readers to specific information within a section of a document by using a
consistent system of headings and headers at the top of each page.

Chapter 13 of Markel and unit 7 of the course guide survey design concepts and elements and
the ways in which they can help you achieve an effective document design. As you read these
sections, look at the illustrations of the various design elements, such as page grids, typography,
headings, and methods for accessing, emphasizing, and organizing information. These
illustrations show how the design elements work together to visually signal the organization of
information. This visual organization structure of a document helps readers find and understand
information.
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 34 of 73
As you read chapter 13, consider these principles of page design: balance, consistency, and
simplicity. Balance is the equal interaction of the elements on the page so that it is pleasing to
the eye. Consistency refers to use of the same patterns on a page. Simplicity refers to not
cluttering the
page with too many elements. Keep the design simple and clean. Markel discusses these
principles in greater detail.

Pay particular attention to the "Learning Theory and Its Relation to Page Design" section in
Markel's chapter 13 (339). It presents three important principles of learning theory—
chunking, queuing, and filtering—that will help you design effective documents.

Chunking, or presenting information in small units, is an important principle to apply to your

document design. It helps your readers more easily comprehend the information. You can use
chunking to separate independent units of information as well as to group related information.
For example, suppose you need to explain a long, complex new personnel policy. Here are some
tools used in chunking that you might consider to avoid glazed eyes and foggy minds among
your readers:

 typography: type families, point sizes, and attributes such as bolding and italics
 page grids: columns and white space
 methods of emphasizing information: short paragraphs, lists, and graphics
 methods of enhancing information access: headings, tables of contents, and indexes

You can apply chunking to all levels of your document, from sentences to paragraphs to
entire sections.

Queuing means arranging information chunks in a pattern indicating their level of importance.
You may think of queuing as the visual hierarchy of information. An example of queuing is the
different levels of headings used in a document. In this module, for instance, you recognize
overview, objectives, and commentary as first-level headings. Within the commentary section,
you see these subheadings, or second-level headings: Designing Documents, Using Graphics,
Developing Instructions, and Developing Technical Descriptions. These headings create a visual
pattern
showing you how the information in the module is arranged.

Filtering is the identification of various types of information within a document so readers can
find what they need. Examples of filtering are the use of icons to indicate specific types of
information, such as overviews, in a user manual or a defined style for a heading that indicates a
summary at the beginning of each section of a report. You can use filtering to direct different
groups of readers to specific information in a document.

Using Graphics

You can see numerous examples of graphics in technical documents. Some examples are

 illustrations in technology-related articles in newspapers and general-interest magazines

 diagrams of objects, materials, and equipment in repair manuals and instructions
 graphs of stock market performance in financial documents
 tables summarizing survey results in a report
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 35 of 73
Look around your office, home, or the Web and you'll likely find an example nearby.

Graphics in technical documents serve a variety of purposes, such as to summarize data, show
how something works, depict relationships, compare and contrast variations in data, forecast
trends, and increase reader interest. Graphics are especially beneficial to communicate hard-to-
explain information such as how e-mail is transmitted, to describe abstract ideas to readers
unfamiliar with them, and to explain information to multicultural audiences. Chapter 14 of
Markel and unit 7 of the course guide discuss the reasons for and benefits of including graphics
in a document.

When planning and selecting graphics for a document, consider your audience and purpose.
Look at such factors as the readers' level of knowledge and interest in the topic and their
expected use of the information.

For example, suppose you are preparing a report for your organization's management showing
the costs of the information technology (IT) department's projects for the last six months.
Management staff of both IT and financial departments will also use the report. What types of
graphics can you use to illustrate the costs in this report? Here are three possibilities:

1. A pie chart to depict the percentages of different types of expenditures as an overview of

the costs. This graphic will introduce readers to the projects on which IT spent money
during this period.
2. A line graph to show trends in expenditures over the past six months. This graphic will help
IT management determine trends in project expenditures and help them plan for the future.
3. A table to show detailed expenditures. This graphic will help financial department staff
identify and verify IT's expenditures.

There are a variety of graphics—tables, pie charts, line and bar graphs, diagrams, and
photographs to visually communicate your information. Chapter 14 of Markel describes the types
of graphics and when to use them.

Text and graphics work together in a document to convey your message. Therefore, they should
be integrated effectively to create a unified presentation. This need for integration may sound
obvious, but often it isn't. Unit 7 of the course guide discusses guidelines for integrating
graphics into text. There is a good example of effective text-graphics integration on pp. 7—21
to 7—24. Apply these guidelines whenever you are merging graphics and text in technical
documents.

Next, we discuss two types of technical writing, instructions and technical descriptions, in
which graphics and page design frequently play an important role in communicating the
information.

Developing Technical Descriptions

Technical descriptions explain how equipment, machines, or objects operate and are assembled
and what happens during a process. A process can include an event, such as a hurricane, or an
activity, such as the transmission of an e-mail message.

When describing an object or process, determine your purpose and analyze your audience's
Ver
needs before beginning to write. The primary audience of technical descriptions is often
people who are
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 36 of 73
unfamiliar with the object or process. Use the questions about audience presented in Markel and
unit 9 of the course guide to learn more about your readers. Your purpose and your readers'
needs should guide you in selecting the level of technicality and detail to include in your
technical description. In addition, look at the discussion about adapting your technical
description to different audiences in unit 9 of the course guide.

The characteristics of a technical description help readers develop a mental image of an object
or an understanding of the flow of a process. These characteristics are the language, use of
active or passive voice, indicative mood, person, partitioning, and graphics. The language used
in technical descriptions should be clear, specific, and concrete.

A technical description concentrates on the object or process. To help readers focus most on
the topic, such descriptions are written in the third-person. When describing how an object is
put together or a process occurs, select factual, verifiable information. Use the indicative
mood for presenting facts, opinions, and questions.

Effective partitioning is important in a technical description. Similar to chunking, partitioning is

the breaking down of the object into its components or the process into a series of smaller,
related steps or stages. Partitioning can help readers understand how the object is constructed
and operates or what happens during each step of a process. Technical descriptions should be
organized according
to the partitioning of the object or process. You can organize your object description into three
patterns: spatial, chronological, or priority. Always organize a process explanation
chronologically.

Graphics illustrate how the parts of an object fit together or the steps of a process occur. They are
used in technical descriptions to illustrate an object and its parts, to summarize the flow of a
process, and to explain abstract concepts. Graphics are especially beneficial for visually oriented
or multicultural readers.

Documents often combine technical descriptions with other types of technical writing, such as
reports, proposals, manuals, or Web sites. Look at the examples of technical descriptions in
the "Analyzing Some Descriptions" section of chapter 9 of Markel, and notice how they were
adapted for different audiences and purposes.

Technical communication
Figure 1 below shows how the development and production of technical documentation
are determined by the three areas of standards, requirements and design.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 37 of 73
 Figure 1: The place of production in creating technical documentation

The processes of gathering requirements, of applying standards, and of using various

technologies in design, have all evolved as the need of technical documentation itself has come
into existence.
In Australia, the Society for Technical Communication (STC) was first formed by technical writers
50 years ago to create aircraft and engineering equipment manuals and other instructions, books,
lists and guides. The STC membership list helps describe the area of technical communication.
Members include technical writers, editors, graphic designers, videographers, multimedia artists,
web and intranet information designers, translators and others whose work involves making
technical information available to anyone who needs it.
The STC definition of technical writing is: „The process of gathering information from experts and
presenting it to an audience in a clear, easily understandable form‟.

The need for technical documents

There is a range of reasons why technical documents are important; think about the
different contributors to documents, as you reflect on their many purposes.
Technical documents help people to build, operate, repair or maintain equipment and systems.
Think of how much complex equipment there is in our world and how fast it is changing. All
of it must have user manuals, guides and other reference material to be useful.
Technical documents help people to understand complex technologies, events or practices, for
example, integrated circuits, microprocessors, nuclear reactors, the greenhouse effect,
Alzheimer‟s disease, acid rain, or earthquakes.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 38 of 73
Technical documents help people to share new technical ideas with others, to introduce
new products, new ways of doing things and new ways of understanding things.
Technical documents help people see the technical, financial, or social value of new ideas.
Think of the amount of information needed in a report that compares different plans for traffic
control, generation of electricity, or waste treatment and disposal. Without good skills in report
organisation and an ability to design effective graphic aids, particularly, tables, charts, and
graphs, these reports can be almost unreadable, like a quagmire of uncontrolled and unorganised
facts.
Technical documents also provide records of events that have a technical element to them.
Network crashes, large loss of data, tests for new equipment, and unusual events, like a hacker
break in, are all documented in technical reports. This ensures the knowledge about such events
is available for further study or reference.
IT technical writers
While specialist engineering technical writers and technical illustrators produce manuals
for buildings, roads, planes, cars, electrical systems, and ships, just to mention a few
areas, many technical writers work within IT and communications industries.
An IT technical writer is any person responsible for writing hardware and software
documentation, online help, technical definitions and technical product descriptions for
publication on paper, or on web sites.
The IT technical writer may be an expert in the subject, with little experience in
documentation, except that learned in training. Or a professional writer may be employed to
help the expert. More often, producing documents falls to programmers and other developers
with little experience or training in technical writing.
Technical writing is necessary for almost anyone who works in IT, communications or systems.
The main skill that professionals among this group of writers bring to their work is experience in
striving to make complicated work simple.
To produce documents that support technology and users you must constantly solve problems
and find answers and solutions.
While documents are assembled, corrected and edited using software applications, and while it
is a technical process, with technical and not imaginative content, is still a process of creation
—an art. You have no automated processes or computers to tell you if the work is „good‟ or not.

Gathering information
Information for technical documents might be acquired by converting it from another
source, collected it from other documents, or by being newly written (on the basis of the
expertise or research from you or other people).
Information needed might not have been originally designed for your document; it may exist in
a different format and the language or structure may need to be converted. Word processing
software can also „import‟ and „export‟ material from other applications, which might then need to
be amended. Information from a database, for instance, might need some unnecessary content
deleted and the work reformatted.
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 39 of 73
 Information may come from textbooks, web sources (such as a manufacturer‟s web site), to then be
incorporated into a document.

If information is used directly from other sources, those References

sources need to be acknowledged, and if there is enough Listing sources for
material used directly, copyright permission needs to be material in technical
sought. documentation
is important. This might also
Creating content
be done by cross
More often, the ideas and words may derive references or links to
more generally from research, or they may be information elsewhere that
related directly to the new system, process or the reader may need.
Copyright
product that has been created and which needs to
be described. The basics of what you need
to know about copyright are
covered in free information
sheets from the Australian
Copyright Council at
http://www.copyright.org.au

To start your document, you might need to write by hand, to type, to draw, sketch, record or to
take photographs or record video footage. Your work will always start with research and
gathering information. Your goal is to collect answers in many forms.
You may need the help of other people with specialist creative skills, as well as the technical
experts. You may hire technicians, professional writers, professional editors, graphic artists or
photographers as contributors—depending on the scope of the documentation and the best ways
of presenting that type of information. In smaller projects, you might do all the work yourself by
being the sole creator of the documents and „wearing several hats‟ as specialist, reviewer, researcher,
writer and editor.

Writing skills
The first skill of a writer is being a reader. The skills of all writers begin with ideas and
understanding them. For technical writing that skill involves gathering information, or
having some basis of expertise, and it often involves a combination of both. Writing
techniques or skills then help relate that information clearly and simply to others.
The basics of writing skills, discussed below, can be grouped as follows.
Preparing to write your document
 Plan your document and create an outline
 Know you audience
 Be prepared with references and non-text components
 Begin a first draft.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 40 of 73
 Using plain English
 Use everyday language
 Use technical words appropriate to the audience
 Use proprietary names and acronyms with care
 Use short and simple sentences, brief paragraphs and lists
 Use active rather than passive voice
 Avoid jargon
 Choose concrete rather than abstract words.
Preparing to write your document

Planning
First, make sure you are clear about what you need to say in this technical document and why
you are writing it. You should have documents that tell you what the document specifications
are and what the user‟s need.
You will also have a template that will help you format the document. You need not about exact
formatting until you‟ve finished writing, but the heading hierarchy and other features in the
template can help you to keep focussed and to structure the document.
The fastest way to write is to start with an outline. It‟s like a shopping list of what you have to tell
the reader. The topics in the outline will become the main points of paragraphs. It is easier to
organise an outline than a whole document. It is much easier to re-organise a document at the
outline stage by moving phrases around, rather than move entire chapters and sections around
after the document is finished.
Know your audience
Who are you writing for? Knowing your audience is important as it helps you choose the right
language and level of detail. Adapt your document‟s content to the knowledge and interest levels
of the audience.
If you haven‟t done so already, talk to some people who might use the document. Ask them what
they need.
Be prepared with references and non-text components
List any references to information in other documents before you write the content. This allows
you to put references into the text as you type your document. This may sound like a minor
point, but it will save you time.
At this point, review the outline you‟ve made for your content and determine the diagrams,
tables, and other non-text devices that can or should be used to add meaning to the
information. The old saying, „A picture is worth a thousand words‟ is true. If you have your
figures, charts, and tables ready, it is much easier to „let them do the talking‟ and write around
them.

VerManual Level III

TTLM Development Competency Title Create Technical Documentation Page 41 of 73
Begin a first draft—just do it
Start with the first or second paragraph or section. Once you start to write, keep going. Try not
to stop in the time you have allotted to do it (unless you have to eat or sleep of course). Don‟t
start with the title page; it is best to save this for last.
It is easier to write without worrying about corrections during the first draft. This allows
you to maintain focus of the topic.
Using plain English
The best advice for writing technical documents is to write clearly, in plain English. Good
writing, whether technical or general, presents information in a clear style.
Plain English for technical writing is that which can be read, understood and acted upon on the
first reading. Plain English needs good design and layout as well as good language, and is
suitable for all kinds of technical information. A golden rule is that plain English should be used
in any information that people rely on when they make decisions.
You may find that one guide for technical writing clearly recommends the use of short sentences,
everyday words and personal pronouns (such as „I‟, „we‟, and „you‟). Another guide might suggest
the use of the third person for technical writing. This is where style guides make a big difference
in ensuring the consistency of your writing. Whatever you do, do it consistently.
Some general principles follow.
Use everyday language
Your writing will be easier to understand if you use plain, everyday language. This is not just a
matter of replacing long or elaborate words with plain words, as you might rightly expect readers
to understand technical words (discussed next). For text in which technical terms occur you can
write
in the same kind of language you would use if you were talking directly to the reader. Table 1 has a
few examples of expressions commonly used, with some clearer alternatives.

Table 1: Examples of everyday alternatives to phrases

Phrase Alternative
Currently Now
At such times as/ In the event that When/If
Prior to and following Before and after
A significant amount of/ The majority of Many/ Most
Has the capacity to Can

Use technical words appropriate to the audience

The use of technical terms depends on the level of skill of your users. In a manual for skilled users
of a technology, technical jargon can be a short-cut to information. For those just learning, the
same terms might make understanding difficult.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 42 of 73
 Technical terms can‟t be avoided in technical documents. But the appearance of technical words
doesn‟t mean that the work must be difficult to for users to understand. Table 2 has examples
of acceptable technical terms used in different documents. To substitute another word could
cause confusion.

Table 2: Examples of acceptable technical terms

Term Meaning
data rate The speed in bits of data being moved from one place to
another. Generally, it refers to the speed of the flow of data
measured in bits across a network, through an Internet
connection, or from a device such as a disk drive.
firewall A firewall is used on some networks to provide added security
by blocking access to certain services in the private network
from
the rest of the Internet or other networks. A computer
firewall (to use an analogy), operates in the same way that a
firewall in a building does in keeping fire from spreading.
kernel The kernel is the set of functions that make up an operating
system, the essential centre. A kernel can be contrasted
with a shell, the outermost part of an operating system that
interacts with user commands. Kernel and shell are terms
used more frequently in DOS, Windows, and UNIX
nanosecond A measurement of time. There are 1,000,000,000 (a billion)
nanoseconds in a second.
serial In computer communications, serial refers to one after
another. Serial data transfer is defined as transmitting data
one bit at a
time, in a stream across one line. The opposite of serial is
parallel,
in which several bits are transmitted concurrently, across
Three principles to keep in mind when using specialist terms:
 Be aware of your audience‟s level of understanding; don‟t be too complex for beginners, or
too simple for experts.
 Use technical terms consistently; technical words should never have double
meanings.
 Provide clear definitions or explanations of terms your readers may be unfamiliar with. Some
documents need use many technical terms, acronyms or abbreviations. To change words that
have real meaning for technicians could cause serious errors.
For example, the word fast, as in „a fast internet connection‟, is really an abstract word and
misleading in IT texts. Yet „fast‟ has very different meanings in medicine (resistant to), mining (a
hard stratum under poorly constructed ground) and painting (colours not affected by light, heat,
or damp). A specialist dictionary is required for learning technical vocabulary.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 43 of 73
Using proprietary names and acronyms with care
A glossary can help remind your reader of meanings. You might also include reference
to an appropriate on-line dictionary (see Resources for web links). Other aids can include
lists of proprietary names and acronyms.
Proprietary names, such as those in Table 3, are the names of products and services developed
and currently owned by one organisation or individual (usually hardware and software).
Proprietary names cannot be left out of most technical documents and when there a great
number pf them a list can help remind readers what exactly is being referred to by each name. If
the same proprietary
name is used by different makers and both occur in the document, it would need to be spelled
out more fully each time (such as Microsoft Office software and Corel Office software, for
instance).

Table 3: Some examples of proprietary names

Name What it is
ActiveX Web page controls for forms to design or collect active data
(as opposed to Java applets).
Java An object oriented programming language created by Sun
Microsystems.
Office Microsoft Office; suites of software including word
processing (Word), a spreadsheet (Excel), graphics and
other options depending on the particular package. Corel
WordPerfect also offers an office. IBM‟s Lotus does also.
When acronyms are first used they must be explained and spelled out with the acronym placed
in brackets. Table 4 has examples. Note how the terms not being capitalised can also make them
more readable (though the use of capitals will depend on the house style for your
documentation).

Table 4: Examples of acronyms

Acronym Meaning
AUP Acceptable use policy (AUP) is a formal set of rules that
governs how a network may be used.
OEM The term original equipment manufacturer (OEM) has come to
mean the companies actually manufacturing or creating
computers, as against those who package and assemble
computers to sell them under a brand name. The term has come
to mean unnamed or unbranded.
OOP Object oriented programming (OEM) is a style of computer
programming which entails building of independent pieces of
code which interact with each other. For example, JAVA and
C++ are object oriented programming languages.
UPS An uninterruptible power supply (UPS) is a standby power
Ver source that provides power to a server or workstation or other
device
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 44 of 73
 from a battery in the event of normal AC power failure.

Simple sentences, brief paragraphs and lists

You may need more words to explain something clearly, and it is best to vary the length of
sentences, but when possible write in short sentences. Shorter sentences make
comprehension
easier. It is also useful to keep this in mind for writing on the web, where users scan for
information, only reading thoroughly when they print texts (as you may have done!).
It is also generally best to have only one or two ideas in each sentence. If you need to also
explain a technical term, use a separate sentence, rather than adding another clause to the
sentence. Also avoid convoluted constructions such as double negatives („not unlikely‟ for
example).
Have one main topic in each paragraph. This helps makes the ideas easier to read and
understand. Keep in mind what journalists call the „inverted pyramid‟ for information. It can help
if the first sentence of a paragraph is like a summary, which is then explained in the next few
sentences. Keep paragraphs brief.
Place long lists in sentences into lists or bullet points under a simple introductory sentence,
with an explanatory sentence to follow, if needed.
Use active rather than passive voice
Technical writers often write in the passive voice. For example:
It is of crucial importance in the workplace that scripts include the provision of
documentation for the utilisation and maintenance of the script by yourself and
other personnel.
Writing the same sentence in the active voice is far more direct:
In the workplace you must provide documentation with your scripts, for yourself and
for others to use and maintain the script.
One change here is having a simple imperative „must‟ replace „It is of crucial importance…that‟.
Another is having verbs do the work in the sentence („provide‟ for „provision‟, „use‟ for
„utilisation‟,
„maintain‟ for „maintenance‟). Note that „documentation‟, as used here, is a technical word—if
you were to change it to „documents‟, the meaning would be imprecise. Also note that there are
times when the passive is the only suitable construction, especially in some scientific writing.
A passive construction may also cause ambiguity by masking responsibility. For instance, the
first sentence does not say whether an investigation will take place while the second (active
construction) makes it clear that it will.
Further investigation will be required to determine the cause of the local area
network failure.
Our IT division will investigate the cause of the local area network failure.
Avoid jargon
Jargon can be a specialised language that only people in an organisation or specialist area understand
(shop talk), or a form that is slang. Or it can be nonsense where no one is really sure of the meaning
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 45 of 73
 (gobbledygook). Most readers are antagonised by jargon and technical writers have a poor
reputation for using it. Avoid jargon when possible, especially:
 undefined acronyms and abbreviations
 non-words, such as slang
 abstract words and phrases
Table 5 lists some common slang terms from IT.

Table 5: IT slang examples

Slang Means
bug A problem with computer software or hardware that causes it
to malfunction or crash.
mickey A unit used in computer science in programming mice and
similar input devices. One mickey is the length of the smallest
detectable movement of the cursor on the screen.
nail up A slang phrase in the telephony industry. The process of
dedicating a telecommunications circuit for a particular use.
The physical or logical dedication of a line for a particular
sneakernet use.
The transfer of electronic information by physically carrying
disks, tape, or some other media from one machine to
another.
vanilla A term used in the computer industry to describe plain
or generic.

Choose concrete rather than abstracts words

What is a device, output or facility? There are times when an abstract term is apt. Yet when such
words are used instead of the concrete or actual object or activity, they can be so vague they
become meaningless. String them together, such as in „output device‟ and you have instant jargon
where printer may have been better. Table 6 has examples of abstract words for which a more
concrete of specific term might be better.

Table 6: Abstract words

• activities • devices • inputs

• amenities • operations • structures
• facilities • aspects • factors
• processes • variables • concepts
• functions • resources • output

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 46 of 73
Ver
 Editing and proof reading stages

Technical review
A technical review is a team evaluation of relevant technical documents. The technical review
of a piece of writing or any other form of technical documentation should be the first level of
review, since it is a waste of time to work on a document that has incorrect content.
Technical reviews are most often conducted by users or specialists. A technical review may
also be conducted by technical referees who are experts in the relevant field. There should also
be another review when the document has been through editorial stages in production, to be
sure no new gremlins have found their way into the work.
The review team identifies deviations from specifications and standards, identifies errors, and
may examine alternative solutions. They provide recommendations for correction of
misinterpretations and for omissions by the writers. The technical review is less formal than the
requirements of approval by the client. The technical review participants often include the
author, and experts in the technical content of the product or service being documented.
Editing stages and tasks
Editing is ideally a distinct task in producing documents, with the writer and reviewer
providing copy to an editor and liaising with that editor to prepare it to be published or
replicated onscreen. Professional editors have a working knowledge of paper-based and screen-
based publishing. Other general areas of knowledge required cover areas of:
 legal and ethical concerns (including copyright and cultural issues)
 design, typography and formatting
 technology relevant to editing practice
 reproduction (including print production and web site and document maintenance).
The Institute of Professional Editors produces the Australian Standards for Editing
Practice. More
information and a web link are in Resources.
Correction and editing take place a number of times when preparing a technical document.
Editing stages can also depend on the extent of editorial intervention which is thought (and
agreed to be) appropriate to a particular publication project. Once guidelines are set for the
document (in the design phase) stages will often run as in Table 7.

Table 7: Sequence of editing stages for print and on-screen

documents

Stage process tasks

Review A technical expert in the subject reviews the draft
document from an author, to check that it is
technically correct and make suggestions for change or
amendment.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 47 of 73
Stage process tasks
Substantive Substantive or Editor liaises with other team members, such as
edit structural a designer or on-screen publishing specialist.
editing Editing queries are resolved with the author or
publisher. Editing tasks made necessary by changes
from queries and the review are incorporated.
Editing to Editing queries are resolved with the author or
Copy edit improve publisher. Editor liaises with other team members, such
meaning as a
and designer or on-screen publishing specialist.
presentation and
to query content. Changes are taken in and any substantive or copy
Copy is In word processing applications templates can be
Formatting provided for designed to convert or carry across formatting to page
formatting layout programs or on-screen mark-up languages (such
and
for print and on- as XML or HTML); formatting to a template will often
programming screen.
have been done at the same time as on-screen copy
editing. Copy is otherwise provided to a typesetter
(especially for book-length manuals) or a programmer
for onscreen versions.
Mark up or At this stage, when the order of typeset pages are final
incorporate (when pagination is set), cross-references to page
Proofread
formatted corrections numbers and the table of contents listings can be
copy of The formatted checked and corrected. An index is commissioned or
paper-based document created at
version (called first this stage.
proofs) is If further changes are made at this stage, necessary
checked against editing and proofreading tasks are repeated. Versions of
the manuscript. marked up and printed documents are then proofed
again
Printer Check proofs (versions calledpages
Sample bound second
andproofs
coversand so on,
from the until ready to
printer
s proofs are given a final check. Sign off for printing.

Proofread Check Any necessary changes are identified. If changes to

formatted screen screen layout and functions are requested, repeat any
copy of on- layout, necessary editing of proofreading tasks.
screen navigation, Proofread corrected (and otherwise changed) screens.
version labelling and Sign off for replication (to CD).
metadata
The focus of editing tasks
Structural integrity
In a longer document, the editor Elements
(and later, the proofreader) checks
 Cover
the

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 48 of 73
Ver
 placement and integrity of any key  Title page
features or elements, such as those
in the list opposite.  Copyright or imprint page
In the substantive editing stage the  Acknowledgements
editor assesses the document to
 Table of contents
make sure that it accomplishes what
it should, and that all the necessary  List of tables and figures
information and elements are or both
supplied.
 Abstract or executive
The list opposite is a likely order of summary
pages for print materials, while
 Preface
depending on the document, the
exact order and the number of  Glossary
elements will be chosen to suit
content. Some  Page numbers
similar elements might exist in  Page numbers
onscreen versions, where
preliminary pages will be home  Headers and footers
pages linked to other screens.  Graphics
Page references in the various  Section dividers/tabs
sections and for the table of contents
would also be inserted, checked and  Electronic links
corrected by the editor, and then
checked again by a proofreader.  Appendixes
The editor would spot check page  Attachments
references in the index for
accuracy, once it is available.  References/bibliography
 Works cited
 Index

With on-screen publications the editor would help also test elements for functionality and
accuracy such as:
 links
 form fields
 feedback items and provisions
 exit sequences
 pop-up boxes
 downloading and opening of files

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 49 of 73
Ver
  metadata coverage and terminology.
Content and style
The editor makes and suggests changes and amendment to help ensure that:
 the document provides complete information for the work
 the information is appropriate
 the content is designed to help the reader understand and find what is needed.
 the order of information is suitable, that is, it is consistently logical or chronological
 the flow of information helps readers to understand
 the information is well structured with signposts, graphical symbols, and heading
styles. The editor also needs to keep in mind a range of style issues, including that:
 the content provided follows the style sheet or guide (if available)
 the writer‟s tone matches the skill of users
 technical words are concrete and accurate
 there is no cultural or gender bias
 any technical terms are appropriate
 the writer uses predominately active voice (except for scientific reports)
 the work has an appropriate point of view (personal when possible)
 grammar and punctuation follow the style for technical documentation
 spelling and capitalisation are correct and consistent (be alert to the damage a
computer spell-check system can do to meaning)
 bulleted and numbered lists are formatted correctly.
Proofreading
Proofreading is a quality control exercise for documents and not a substitute for copy editing.
With larger technical documents, or with projects that have taken a long time, a separate
proofreader may be employed for the job. A fresh view of the document often helps as the author
and editor
may have become so familiar with the documents that they fail to notice remaining errors
and inconsistencies.
Often, however, as is clear in the description of tasks above, the editor‟s scope of work includes
proofreading.
The tasks of proofreading check and ensure:
 Verification of copy (checking against previous copies and checking typeset proofs).

TTLM Development Manual Level III

Ver Competency Title Create Technical Documentation Page 50 of 73
  Integrity checks (of elements described above and also of cover, dust-jacket material,
spine copy, preliminary and homepages, copyright and publication information, and
contact details)
 Spelling and punctuation errors
 Conformity with style specifications (with an editing style sheet and organisational
style guides)
 Conformity with design specifications (heading hierarchies, running heads and
footers, buttons and scroll-overs and labels, fonts, alignment and spacing, page or
screen layout.
 Sequences, cross references and links (including checking all references to tables, etc,
proofread the index, spot check cross references, spot check functionality of links and
page display)
 Layout (including page and screen breaks, word breaks at the ends of lines or
pages, placement of tables and captions, etc).
If a proofreader has been employed, any corrections, errors or inconsistencies found are
marked-up to be referred to the editor to review.
The author and the editor are responsible for careful review and accuracy of all facts, dates,
spellings and corrections. If a proofreader marks up changes for the typesetter to take them in, a
copy should be sent back to the author for approval, showing where the changes have been
made.
Marking up documents
Many technical documents are produced on screen, with changes from various contributors made
to an electronic copy (using some sort of version control).
Technical documents prepared by publishing houses on the other hand, or documents that are to
be especially typeset and bound, often have all changes made to a hardcopy or typeset
document. With some onscreen documents mark up on hard copy might be essential when the
content has already been converted to a mark-up language (such as HTML).
When changes are made by hand they need to be clear and able to be understood by all those
involved. For this reason, standard proofreaders‟ marks or symbols are used to show the nature
of each correction, and the same symbols are used for copy editing and proofreading stages.
Changes are usually shown in the text column and the symbol indicating the change is placed in
the margin the draw attention to the amendment. Changes are marked from left to right. If there
are two changes to make in one line, symbols showing changes are separated by a forward
slash. To allow space symbols for material on the left of column text can be placed in the left
margin and symbols for changes in the right column text marked in the right margin (as shown
in figure 1).

Figure 2: Example of proofreaders marks used in editing

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 51 of 73
Red ink is mostly used, simply because it stands out more, or different colours can be used
according to the type of correction (blue or black for author‟s or editor‟s errors, read for
typesetting errors).
The Australian Government Information Management Office Style Manual for authors, editors
and printers, has an appendix explaining standard proofreading marks and how to use them.
There is also a link to a two-page set of proofreading marks from a UK web site is in Resources
section, and an activity in using proofreaders marks in the Practice section of this Learning
Pack.
Proofreading tips, peer editing and computer tools

Focus tips
For smaller documents and when a professional proofreader cannot be used, the
following proofreading tricks can help find mistakes.
 Read for only one kind of error at a time. If you try to identify and revise too many
things at once, you risk losing focus, and your proofreading will be less effective. For the
less- experienced, it‟s easier to catch grammar errors if you aren‟t checking punctuation and
spelling at the same time. Some of the techniques that work well for spotting one kind of
mistake won‟t catch others.
 Read slowly, and read every word. It‟s OK for your lips to move when you are checking
for errors. Before the age of electronic files, documents copies or galleys from printers
were proofed by one person reading out the text and all punctuation while the other
person checked the other copy. Try reading out loud, which forces you to say each word
and also lets you hear how the words sound together. When you read silently or too
quickly you may skip over errors or make unconscious corrections.
 Separate text into individual sentences. This is another technique to help you to read
every sentence carefully. Simply press the return key after every period so that every
line begins a new sentence. Look for grammar, punctuation, or spelling errors.
 If you‟re working with a printed copy, use an opaque object like a ruler or a piece of paper
to isolate the line you‟re working on.

Peer review and editing

When managers decide that people in their department should be responsible for editing their
own documents, quality control can become a problem, with errors missed and standards
overlooked.
Peer editing is one way of compensating when there is not a distinct editorial role for staff. This
works by having people in your department edit the work of their colleagues. From a point of
view of technical understanding, people in the same department should also be able to review
draft documents and spot errors; they should know the subject matter fairly well, even if they
see the work with different skills. A work culture where group members collaborate to produce
quality documentation is important for peer editing to work well.
Peer editing and review can work by having:
 individual editing
 group editing responsibilities (for longer documents).
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 52 of 73
With group editing, all team members review draft documents. Then they meet as a team to
discuss any problems they find. (A good manager will prevent the group reviews from turning
into a „hunt the writer‟ session.)

Computer spell checks, grammar checks and document control

Spell checkers
Most word processing programs have tools to help in editing and correcting documents. The spell
checker feature is well known. It is also well known for its ability to replace sensible words with
non- sense words, when a writer isn‟t paying attention to the screen, and the document isn‟t
checked carefully. Some of these are words that are in fact correct but in the wrong place, such as
the word
„from‟ instead of „form‟, „of‟ instead of „or‟. A good practice when using spellcheckers is to check for
instances of these particular words to make sure they are correct in each use.
Grammar checkers
Grammar checkers can be useful to a degree, for pointing out passive constructions or
fragments, and for showing errors in such things as singular and plural forms and when
subjects and verbs don‟t agree. Yet with technical documents, especially scientific documents,
you would be best advised to use your own judgement—sole reliance on such tools can
overlook and even introduce errors.
Document control and revisions
For document control Microsoft Word uses a feature called Version, which attaches a
version number to each new draft of a document. This feature is found in the File menu.
Microsoft Word is also one of many word processing packages that allow two versions of a
document to be read and compared side-by-side, on the screen, and when changes are made by
several editors, they can be merged into one document. This utility is called Compare and Merge
Documents, and can be found in the Tools menu (though you are well advised to save a copy for
all documents before doing this).
Tools to monitor revisions also exist in the word processing packages. When corrections have
been made in Microsoft Word by a reviewer or editor, the author can see what has been deleted
and what has been added or changed, by coloured lines in the copy. This feature is called Track
Changes, and can also be found in the Tools menu.
A feature for adding notes and comments is also commonly used for reviewing documents and can
be used for editor‟s queries.
In current versions of Adobe Acrobat, PDF files can also be marked up on-screen to make
changes at a proof stage for documents that have already been typeset or converted to HTML.

10 things you can do to create better documentation

#1: Document with pictures if possible

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 53 of 73
The old adage a picture is worth a thousand words means that by using pictures to augment
your text, you can minimize the length and complexity of your documentation. System users
like having pictures, diagrams, tables, and bulleted lists for quick reference.

#2: Give examples

Examples are an excellent way for end users to quickly grasp concepts that they may not fully
understand. It is also a good way for an end user learning new software to sit down and tackle a
new challenge more easily. Here is an example of documentation with pictures:

Previous Versions in Vista Business, Ultimate, and Enterprise

Previous Versions is the term that Microsoft uses for saving shadow copies of a file. If you are
working on a document or any other project that is labor intensive and have accidentally lost part
or all of your work, you can go back to a previous version. Think of it as an automated way to
make snapshots of how the file looked at previous points in time.

But first you will have to configure Vista so that Previous Versions (Figures B through E)
will be turned on for the logical drives/partitions that you want the ability to restore the
previous versions of your files.

Enabling Previous Versions

Figure B

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 54 of 73
 Select Start | Control Panel

Figure C

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 55 of 73
Ver
 Left click Advanced system settings — Left click Continue if prompted by the UAC (User
Account Control)

Figure D

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 56 of 73
Ver
 Left-click on the System Protection tab

NOTE: The Vista logical drive/partition is already enabled by default. Change this
setting only if you fully understand the consequences of doing so.

Figure E

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 57 of 73
Ver
Scroll down and check logical drive

Left-click on the scroll bar and scroll down through the logical drives/partitions until you find
the one for which you want to enable Previous Versions. That logical drive name is Documents
in this example. Left-click the check box next to the logical drive name.

NOTE: Shadow copies are created based on the time and frequency of system created restore points.
According to the
Vista help file, this is typically once a day.

Left-click Apply and then left-click OK to close the System Properties window. Left-click File |
Close or left-click on the red X box in the upper-right part of the Control Panel | System window
to close it.

To restore the previous version of a file, you can right-click on the filename in Explorer and
left- click Restore previous versions.

NOTE: Once a shadow copy of a file has been restored, it is no longer available for a second
restore. Another shadow copy will not be created until the next system restore point is created.
This means that any files saved before the next system restore point cannot be restored to the
same previous version you used previously. Caution should be exercised saving files after using
the Restore Previous Versions option until the next restore point occurs and another shadow
copy can be created.

#3: Don’t presume to assume

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 58 of 73
Even if you know your targeted user base, your documentation needs to be written so that
anyone with only basic computer skills can read it and learn how to properly use the system.
Step-by-step instructions should be provided when possible, but consider placing them in an
appendix, a separate chapter, or making them available via a hyperlink to avoid clutter. If you
are doing the documentation, change your mindset so that you place yourself in the shoes of a
new system user. That can be difficult to do at first, but if you pay attention to details and fully
document all features and functions, you can create documentation that doesn‟t assume that the
user can figure out information and procedures you have failed to include.

Don‟t assume that your end user understands all of those acronyms that litter the IT landscape. The
first time you present a new acronym, detail what the acronym stands for.

#4: Anticipate problems

When testing your system, you should have tried your best to break the software any way you
could. If your software has known issues (developers like to call them issues; end users call
them bugs), document a workaround and provide it to your users and the help desk. You will not
only save a lot of frustration for the end users but also a lot of extra calls to the help desk.

Document the events that are inevitable during the lifetime of any long-lived system:

 What workarounds are available while the system or network is down?

 How do you recover from a server outage, a hard disk crash, or database corruption?
 How does someone who knows absolutely nothing about your system get the system up and
running
again?

Your documentation should anticipate these problems and provide a detailed plan and
instructions for system recovery.

Will the person who replaces you know where to find your documentation and any purchased
vendor application documentation? All of these documents should be neatly organized and
stored together in a safe and known place.

Another good example of anticipating problems is the Y2K Millennium Bug problem and
solution. The media began reporting in the late 1990s that systems and software were likely to
fail due to the storage of only two digits for the year in legacy systems. This problem was
anticipated in advance and a lot of effort went into fixing the problem before it occurred.
Software in development was built and certified as Y2K compliant years in advance of January
1, 2000. The results were remarkably successful. Except for a few minor reported problems, New
Year‟s Day 2000 was a festive occasion and not a disaster for the IT community, though a lot of
us were on-call just in case.

The same mindset can be used to anticipate problems that might arise in your documentation.
The Y2K problem also illustrates the need for continual document updating. System/Internal
Documentation was changed to note the Y2K compliance or noncompliance of software and
systems. For older legacy systems, workarounds were found and documented.

#5: Test your documentation

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 59 of 73
Sit down and follow your own instructions. If you are documenting the building of a server, a
network, or any other IT system, start with a clean partition and build everything from scratch.
You will undoubtedly discover that you have left something out or that some of your
instructions are unclear.

Work with an uninformed but committed co-worker to get feedback before you publish. Let
them test out your documentation.

You will be amazed at what you will learn when you sit a person down to work with your
software and documentation for the first time. A lot of features of the software that are obvious
to you will not be so obvious to someone who is honest and willing to work with you. Watch
closely what your guinea pig does while navigating your software. Ask for feedback and take
notes.

I remember the feedback I got during the testing of one of my projects. The feedback was written
in an e-mail so I could review it point by point. The first thought that came to mind was “how long
will this take to do?” You may also take these comments as critical or personal. Don‟t make that
mistake. Looking back on it now, I should have implemented more of the missing features that
my helpful critic had provided.

Use this opportunity to make final tweaks to your project. Feedback during the
documentation process can help you make the overall project more successful.

I was writing a review for the Foxconn 975X7AB-8EKRS2H motherboard and I ran across two
errors in the manual. I wasn‟t the first person to review the board. Foxconn had missed the errors
and all of the other reviewers had missed the errors as well. One mistake in the manual was far
from trivial.

The diagram in the manual showing the normal position of the clear CMOS jumper setting
was incorrect. I know because when turning the motherboard over to verify the proper seating
of the heatsink, the jumper fell off. I put the jumper back on according to the instructions in
the manual. The computer failed to POST. After a careful look at the tiny diagram on the
motherboard, I discovered the error and corrected the misplaced jumper.

I was working with a tech from Foxconn at the time who was kind enough to answer my
questions and I informed him of the error. Documentation errors like this are easy to miss and
can lead to potentially large costs to the manufacturer. I would have missed the error myself
were it not for the fact that the jumper had been loose enough to fall off when turning the
motherboard over.

#6: Humanize your work

How many times have you read a user manual and wondered if there really was a human at the
other end of the creation of the manual — or was it a computer that made that manual? Although
you don‟t want to create a colorful novel, humanize the document just enough with some of your
personality so that a reader will feel a little more comfortable while reading it.

#7: Explore new technologies

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 60 of 73
Documentation can be costly even when done correctly. New technologies will continue to be
created to help create more effective documentation that is less costly to develop. Look at these
new tools as opportunities to reduce the time and cost of the documentation process.

Documenting as part of a project team can be especially difficult. Your documentation needs to
be shared and added to the documentation of other team members. Changes have to be made,
often on a daily basis. Software exists that will allow for this and will not only help to ensure a
standardized end product but will also help to foster the sharing of ideas and knowledge among
the team members.

While working at CSC (Computer Sciences Corporation) I had experimented with Microsoft‟s Agent
and text-to-speech technology with mixed results. I always thought that it offered some
wonderful ways to guide a new user through some of the features of my system. Some may
remember that offensive little paper clip character with the blinking eyes in Word 97. It was
slightly more than annoying.

With Agent, you can have your character move across the screen, point to a drop-down box,
programmatically open the drop-down box, and allow the character to speak to you about the
options presented. I created a guided tour of my software and let Peedy, the parrot, point to
boxes, fill in text boxes, change screens, and generally walk the end user through the entire
process of creating a new record in the database.

I found that using Agent saved me from having to write many tedious pages of documentation
that detailed the steps necessary to create, save, and modify new records. It was also fun to
develop. It allowed my creative side to participate in a positive and beneficial way. Creativity is
pre-programmed in most developers and is a key component of what makes them successful.
Creativity can and should be considered when developing your documentation, depending on the
standards and expectations of your company.

The only feedback I received about my MS Agent experiment was that someone had too much
time on their hands and it was never taken seriously, at least in part because of the comical
looking character. It wasn‟t a lot of extra work to build, but it did require me to learn some new
coding techniques. It was a pleasure when a person in our department was to be trained. I told
them to take the guided tour. Perhaps Microsoft was ahead of its time, and with a more
respectable character, this type of technology could still become mainstream one day.

I recently built a computer for my dad as a 50th wedding anniversary gift. I documented some
notes marked Important PC Notes PLEASE Read and left a shortcut on the desktop. I also
created an audio file that documented the features and use of the computer. I had to ask him if he
looked at my
notes, but he offered to tell me that he took the case and computer audio tour.

These are just a few examples of alternative ways to document. It is this humble writer‟s opinion
that new ways to document are underutilized and underestimated for their simplicity and
potential impact in today‟s corporate environment.

The elusive be all and end all documentation software package has yet to be developed, but there
are a number of useful documentation tools that are designed for specific documentation tasks.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 61 of 73
#8: Do the documentation yourself if possible

The best person to document is the builder. After all, who knows the system better than the
system builder?

If you are the system builder, you are likely a crack programmer. But just mention the word
document to a programmer and you will be given that “you‟ve got to be kidding” look. If forced,
programmers will document their work, or at least make an attempt to create something that will
pass as documentation. I know. I have seen it all too often and even been guilty of it myself.

And that is a real shame because a programmer with good documentation skills is a valuable
asset to the company. What will your manager remember at performance review time if another
person had to do the documentation for your project? My guess is it won‟t be that you deserve a
promotion, raise, or bonus.

While not exactly fun, documentation can be rewarding when done correctly. Not only will you
have a better overall project to present to your customer, you will also greatly reduce the future
support time you will have to provide. You can also reduce the amount of support and
maintenance time for the help desk.

When working at CSC, I was given the opportunity to be the project lead for the design and
creation of our global reporting system and infrastructure. I got to see first hand the other side of
documentation. We had a very good programmer in the group who was doing Crystal Reports
API work and custom function building. It was obvious to me that his knowledge was unique to
him and needed to be shared with the rest of the team, and what better way to do that than to
properly document his work? I wasn‟t entirely successful in getting him to explain his work to the
point that another person could step in and pick it up. He did list and explain the function names,
how to use them, how they worked, and what they accomplished, and that was very helpful to the
other members of the team.

There seems to be an unwritten rule in the Realm of the Code that programming skills are
inversely proportional to the amount of documentation programmers have to do.

The second greatest compliment ever paid to me in my career was when I had to give a
presentation to our global technical support team. I had to create and present documentation on
how to build a reporting server. One of our database administrators was a chap from England
who had to sit in on the presentation. He looked at the How to Build a Reporting Sever document
and, to paraphrase, commented how good the documentation was and that he should be able to
build a reporting server using my documentation. Statements like that make all of the hard work
worth it. And it wasn‟t a compliment for the main project work — it was for the documentation.

#9: Coordinate the development of the End User Documentation with the Internal/System
Documentation

You can cut your documentation time if you build your User Documentation at the same time
you write the System Documentation. You can share some of the information between the two
and reduce missing information. Even if you don‟t want to or it is inappropriate to share
information

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 62 of 73
between the documents, you can benefit from topics in one document that will prompt you
to include additional documentation in the other.

#10: Follow department or corporate documentation guidelines

Create and follow standard formats and guidelines. This will help to ensure that
important information is not excluded and allow for easier reading by system users.

The one time I had a dedicated documentation expert work with me to document my system was
at Hughes Aircraft Company. The results were excellent. The format was the department
standard and the results were better than I would have done. It required a lot of time and effort to
get those results. The documentation expert needed access to my beta system and access to me
so that I could answer questions. This is more expensive and not all companies have the
resources to allocate to professional documentation, but the results can be excellent if the system
builder can verify that important information is not misinterpreted or left out of the end product.

I was very fortunate that I had a former engineer who was also excellent at writing
documentation. He understood what the system was designed and built to do and he filled in
the blanks by actually using the system and discovering for himself how it worked. You may
not be so fortunate.

In this day and age of global marketing, sales, and support, documentation should also follow
country or regional standards. I am often irritated reading the manual for a piece of electronic
gear made in China that is all too often difficult to translate. It is written in Chinglish and for
some sentences I have to pause and try to comprehend. I usually just make a mental Scooby
Doo sound and move on to the rest of the manual.

Were English-speaking documentation pros to learn (they never do) and write in Chinese, I
imagine their Englese would sound the same to the Chinese-speaking people. Find and use a
professional translator to make the documentation understandable so that important information
is not lost in translation.

I should also state the obvious. Your documentation should be free of misspelling and
grammatical errors. Always use a spell-checker to find errors. I never cease to be amazed at
how many obvious spelling errors I have made and simply missed on a reread.

Summary
Quality documentation is everyone‟s responsibility.
This reading has outlined some basic methods, stages and industry practices for producing
technical documentation. You‟ve considered tasks from gathering information and using plain
English, to editing and proofreading tasks for print and onscreen documents, with a clear
summary of what is involved.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 63 of 73
 Progress
Have a look at the next section—Activity. If you have trouble, review these Readings or
perhaps take a look at some of the listed Resources.
When you feel ready, try the Self check section at the end of this topic. This will help you
decide if you are now able to complete the task and attempt assessment.

LO4:Evaluate and edit documentation

Inside this reading

The purposes of client sign-off

How sign-off works
Sign-off times

Approval checklists for paper-based and onscreen documentation

Strategies for gaining sign-off

Communicating the process

Summary
Check your progress

The purposes of client sign-off

Figure 1 below shows sign-off as the end point before technical documentation is published
or reproduced. It is also an end point to crucial stages during production.

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 64 of 73
Ver
 Figure 1: The place of client sign-off in creating technical documentation

How sign-off works

Client sign-off can occur for various points in the design and production of documentation. Sign-
off makes certain people accountable for the completion of various stages. Those with authority
to sign can be accountable for the cost of documentation and its quality and integrity, or both. It
is the
client who decides when the work is completed and functional.
Acceptance is based upon the success criteria defined in the very early initiating and planning
stages of the work. Sign-off therefore also helps to define and structure the stages of
development and production.
When documentation is submitted to be signed off, changes are often needed in response to
feedback before sign off can occur. The phases or steps can be much like those in project
management or systems development. As the point of each „deliverable‟ is reached, the client or
a subject expert needs to review and approve the work to this stage. This feedback gives all
participants the chance to correct flaws.
Controlling the development of technical documents is also very similar to project
management. Clear, manageable and efficient procedures must be in place to handle version
control, change control, document updating, and distribution as the work progresses.
The final sign-off on technical documentation is often a crucial stage in the completion of IT
projects. When documentation is signed off it ensures that:
 the original specifications and requirements criteria for documentation are being met

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 65 of 73
  there is formal acceptance, in writing, that the client, project manager or sponsor
have accepted the documents are complete and accurate
 work by outside contractors or suppliers is formally accepted (and paid for)
 documents are authorised for final production and distribution.
The final decision to sign-off comes from the client. But the client will often need to listen to
other people within an organisation, including those who steer the organisation, who pay the
bills, the users and any experts who have contributed to documentation.
Each of the following stakeholders, for instance, may approve the design and planned use
of technical documents.
 Business units may have requirements that depend on the content and accessibility of
all documentation.
 Administration may need to ensure that documentation management will comply
with external and internal constraints, such as ISO 9000 Quality Standards.
 The IT group may be obliged to support and maintain digital documentation,
storage, hardware and programs, communications, and compatibility within
existing systems.
 Audit and accounting staff may need to ensure that documentation
accommodates organisational financial policies and obligations.
 Legal counsel may review documents for legal consequences and contractual
implications. You can see from this list that sign-off on technical documentation can involve a
broad team of
people. Methods are needed to manage the approval of a range of stakeholders.
Sign-off times
For technical documents, signed client approval and review by other stakeholders are generally
required at the outset of planning, where the project is approved, and again at the end of the
project.
However, at each deliverable stage, especially for the end of each draft, a technical expert
might review and endorse the writer‟s or graphic artist‟s work. Confirmation is also needed
that recommended changes are included in the next draft.
By the final draft, expert review of the document is needed. It is also wise at this stage to test
the document with a review by eventual users. These are the people to whom clear usability
of the document is essential. Then, when agreement is reached or the work is ready to be
passed from developer to client, someone in authority needs to sign on the dotted line for
reproduction.
Procedures for sign-off
Most organisations will have procedures for documentation sign-off that are similar to the
procedures followed to approve projects. Table 1, on the next page, outlines stages at which
the plans for documents, or the documents themselves, might be subject to formal approval.

Table 1: Some likely sign-off points for technical documentation

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 66 of 73
 Phase Activity Related approvals
Planning Project initiation Feasibility report approval
Content The determination of Approval of scope
specificatio the scope of client document and
n requirements and the scope publishing schedule or
of work timeline
Implementation Development completion Approval of technical review
Production and Design completions Client validation and
evaluation approval of technical
documentation
Completion of structure
Review and user
documentation testing approval
Approval of printers
proofs or web site screens,
or both

Approval checklists for paper-based and onscreen documentation

For both print and onscreen documents a range of elements may need to be checked
before approval to publish them is sought.
A checklist prior to sign-off might include each individual component as in Table 2 for
print materials, where final checks before going to print would include making sure
document design styles have been applied correctly.

Table 2: Sign-off checklist for print materials—elements

Cover Page numbers

Title page Headers and footers
Copyright or imprint Graphics
page (ISBN or ISSN or
both, copyright
statement)
Acknowledgements Section dividers/tabs
Table of contents Electronic links
List of tables and figures Appendixes
or both
Abstract or executive summary Attachments

Preface References/bibliography

Glossary Works cited

Page numbers Index

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 67 of 73
Ver
A summary checklist for onscreen documents is more elaborate, since the onscreen
presentation requires content that may not have yet been checked in an editing process (as
content will have been). A useful general pre-approval checklist is shown in Table 3 on the
next page.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 68 of 73
 Table 3: Pre-approval checklist for electronic documents

Identification details
Are the document owner (or sponsor), title and author identified?
Are standard document identifiers attached: ISBN or ISSN or
both, library metadata, copyright statement?
Are acknowledgements included (if needed)?
Are references made to any related or associated print
documentation?
Is the date of publication (and the most recent revision) shown?
Have contact details and any relevant feedback links been given?
Legal aspects
Has a disclaimer statement been included (if needed)?
Design and navigation
Does the design reflect the corporate or in-house image or identity?
Do pages and screens suit screen characteristics (such as size,
shape and resolution)?
Are there the kinds of search facilities users need (topics index,
key word searching, etc)?
Do all colour images meet the web 216 colour standard for the
Internet?
Where relevant, are the navigation elements on every screen linked
to any larger information structure (such as a home page or host
web site)?
Are there clear pathways within the documentation and is each
page suitable linked (that is, no dead end pages)?
Access and transmission
Are the file formats appropriate?
Have bandwidth, access speeds, file sizes and browser
compatibility been taken into account.
Does it meet W3C guidelines for web access?
Testing and evaluation
Are readers able to find the documentation using search engines?
Is it easily opened and printed (if necessary)?
Do navigation features work correctly?
Will the screen display match expectations?

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 69 of 73
Ver
Approval methods
Methods used to gain sign-off might include consent forms, circulation lists or some form
of electronic approval.
Consent forms
A sign-off consent form might sensibly include the following elements:
 A title, saying what it is that you want the client or executive to approve (a design
plan, a form, a template etc).
 A reference to the role this document will play in an over-all project or system.
 A description of what is being agreed to including a description of what has been reviewed.
 An explanation of how any later changes to the documentation may be handled after
the form has been signed.
 In cases where work has been done under contract, especially for an agreed-to
deliverable, permission to issue an invoice might also be included.
 Space for signing and dating.
Circulation list
Sign-off of smaller technical documents may be served with a distribution list. The work to be
approved might be circulated to a number of executives and experts, along with approval
checklists such as those in Tables 2 and 3 above, or checklists that are specific to particular
people‟s expertise.
Each person on the circulation list is required to review the work, add comments and forward the
document to the next person on the list. (It is essential that you keep track of the progress of the
documents). When the comments and signatures are all returned, and you have incorporated
valid changes into the master documents, you will need to re-circulate the documents, so
contributors can see what changes have been made or incorporated. (For print documents,
Microsoft Word is one of many applications that have features to help with the group review of
documents in this way.) Table
4 is an example of a simple circulation checklist.

Table 4: Sample circulation list

Name Position Signature Date

W.E. Knowall Project manager
I. M. There IT Manager
Will. Power Legal
P. Encil Administration
J Blow File Librarian
T. Opdog Corporate Secretary
Tom Piper Jnr Technical writer
Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 70 of 73
Electronic approvals
A document can be reviewed, agreed with and approved on-screen. A typical example is an
end- user-license agreement (ULA), where terms of the agreement are displayed, and nothing
more can happen until the user clicks „I agree‟ to confirm a contract with the software
developer.
Similarly approval of technical documents can be done using secure technology, such as
digital certificates, to ensure that a signature is authentic and not copied by another person
from another source. (A signature that has been scanned from a paper document and included
in an electronic document is not a legal signature).

Strategies for gaining sign-off

Communicating the process

After all the stages of design and production, you still need to be well prepared when seeking
final sign-off on technical documentation. In addition to being on top of the subject and
purpose of documentation, you may need to know:
 the business the organisation operates in
 your organisation‟s ways of doing business.
While the purposes and procedures for sign-off may be clear, a client‟s sign-off and agreeing to
accept the hand-over of a finished product should not be seen as a simple formality. Many
projects stumble and fail at this last hurdle, because approval was a process that was taken for
granted.
You should sometimes be prepared for a less-than-smooth ride when you want work approved—
even after all the elements of documentation have been thoroughly double-checked.
A novice may request sign-off without care and planning. A report is sent to a client, attached to
an email, asking for agreement, or sent by a messenger or courier. This could turn out to be a
bad
move. The request could sit in the client‟s „too hard basket‟ for days. When the manager gets around
to reading the request, there may be questions about details, so it goes back into the „pending‟ tray.
Asking for a manager‟s approval for a document is very basic and often taken for granted—
beginners may forget to ask for signature on the sign-off form directly, personally and clearly.
One approach can be to ask for a meeting, for handover, not for sign-off. Have your team of
technical experts on call, to present the technical details, in simple language. Include your final
checklists for scrutiny.
More simply, phone the client first, or see them, and tell them the relevant draft of
documentation (or drafts of an information set) is being sent to them and ask if they could
respond soon as possible. Their reply and signature is often much quicker if you do it this way.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 71 of 73
 How to Edit Your Own Technical Document

It‟s best to have a colleague or an outside reviewer to read and edit your technical documents.
But sometimes you might now have that luxury and you may be all alone.

So how should you edit your own stuff?

I can only give you a few tips that worked for me in the past.

(1) First off — the OBVIOUS — put your document through a Spell Checker. You‟d be amazed
how many writers forget to do that. That will certainly catch the roughest mistakes.

But that‟s not enough. For example, the spell checker won‟t catch “right” misspelled as “might”
since both words are spelled correctly but only the former is correct semantically.

(2) Check your links. In FrameMaker this is so easy. You make a search for “Unresolved Cross-
Reference”. Period.

(3) Read all your figure CAPTIONS and table TITLES. Make sure they are correct.

(4) Check your procedural steps and make sure they all start with an ACTION VERB. A
description should not be a numbered step in a procedure.

(5) Make sure every acronym is written in open form at least once, preferably, the first time
you use it.

(6) Make sure your conjunctives (and, or, etc.) are necessary. That‟s a habit carried over
from the way we usually speak, by inserting all kinds of “and”s and “like”s, etc. in between our
independent clauses. If not, they‟ll lead to unnecessarily complex compound sentences.

For example, take this sentence: “The dial show 200 volts and that‟s something you should report
to your manager.”

You can re-write it as two separate sentences: “The dial show 200 volts. You should report that to
your manager.”

Or again a single sentence, written as a conditional (IF) sentence: “If the dial show 200 volts,
report that to your manager.”

(7) Scan your whole text from REVERSE! Yes, I‟m not joking. It‟s amazing the things you can
catch when you flip through a document by starting at the last page and going backwards to the
very first page. That circumvents the mind‟s built-in structuring reflex and thus helps you see
spelling errors much more quickly. It works.

TTLM Development Manual Level III Competency Title Create Technical Documentation Page 72 of 73
Ver
Summary
This reading has outlined the purposes of sign-off on technical documentation as the formal
recognition and approval of various stages of development, and especially final approval, as the
end point that helps assure all the prior stages of quality control.
Editing and proofreading stages, including technical review, can be subject to formal approval
and sign-off. The response to feedback when work is submitted for sign-off is also an important
review process in itself and helps validate the content, scope and usability of technical
documentation. Summary checklists can help assure the quality of documentation before
approval is sought.
Part of designing and producing technical documentation is being an advocate for the
usefulness of the processes involved. You may need to communicate this clearly to gain sign-
off.
Check your progress
Now you should try and do the Practice activities in this topic. If you‟ve already tried them, have
another go and see if you can improve your responses.
When you feel ready, try the „Check your understanding‟ activity in the Preview section of this
topic. This will help you decide if you‟re ready for assessment.

Ver
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 73 of 73