Creating Technical Documentation TTLM Final

Ethiopian TVET System Entoto TVET College
HARDWARE AND NETWORK SERVICING

Level III
LEARNING GUIDE # 1
Unit of Competence: Creating Technical Documentation

Module Title: Create Technical Documentation
NOMINAL DURATION: 70
LEARNING OUTCOME:
 Identify and analyze documentation needs
 Design documentation
 Develop documentation
 Evaluate and edit documentation
TTLM Development Manual Level III Competency Title Create Technical Documentation Page 1 of 73
Ermiyas W.
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
Ermiyas W.
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
Ermiyas W.
thiopian TVET System Entoto TVET College
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
precondition for the later design, review and production of documents. If requirement specifications
Ermiyas W.
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
Ermiyas W.
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?
Ermiyas W.
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
Examples to
consider for
technical
documentati
on
Comments
Business Technical Functional Information
requirements requirements requirements requirement
s
Compliance, Available Common use, Accuracy,
Value, Security, technology, System processes Circulation,
Disaster Existing systems, or performance, Usefulness,
recovery, Accessibility, Data archiving, Copyright,
Reporting Compatibility, Audits and Validation,
functions, Environment, controls, System Content,
Interface Hosting, Location administration, Format,
functions Conversion from Deployment
one format to
another
Documents are The platform for Can the users Does the
used for your operating capture process of
decisions and system may dictate information that is documenting
reference. The what applications required, store the information
Ermiyas W.
business case for can manage information and support the

documents, the documents. Also, publish information
goals, and the available hardware, information as needs. Does
scope of software, required, and the system
documentation stationery, and move information allow for
and sponsorship facilities need to to other domains. changing
of the project are be considered. needs?
all
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.
Ermiyas W.
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.
Is there anything missing? Better to have stakeholders

Complete?
review the specifications now, than have problems later.
Are there conflicts with any other requirement, or other

Dependable? parts of the system?
Is the requirement simple, short and to the point?

Concise?
Is the source of the requirement documented? Are reviews
Acknowledged? cross referred to the source for a double check?
Can other people readily find and identify this requirement,

Identified? 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.
Ermiyas W.
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.
Ermiyas W.
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:
Ermiyas W.
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
Ermiyas W.
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.
Ermiyas W.
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  measurements
 analysis  statistics
 instructions design
 reviews s
 records report
s
 discussion.
A good technical document:

 meets a need
 serves an audience
Ermiyas W.
 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 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
Ermiyas W.
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:
Ermiyas W.
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.
Ermiyas W.
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) backed- checksum help desk
up (verb) desk check HTTPs host ID (two
CD-ROM dial-up parts)
coordinate downtime ID (no need to spell-
copyfree flow chart out)
copyleft 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)
Ermiyas W.
STU VWX
subnet and subnetting web
sub-layer web site (two words)
time frame (two 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.
Ermiyas W.
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
Ermiyas W.
 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 hierarchy (or
labels) with the higher level having a larger font). Hierarchical presentation begins at the top level,
Ermiyas W.
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 technical
consistency documents within an organisation the same; users then
Ermiyas W.
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.
Ermiyas W.
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.
Ermiyas W.
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.
Ermiyas W.
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:
Ermiyas W.
 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
Ermiyas W.
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.
Ermiyas W.
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.
Ermiyas W.
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 matter Examples

other than
works
Ermiyas W.
Literary novels, poems, song Cinematograph films, videos,

lyrics, newspaper and films DVDs, Flash
journal articles, essays, animations
reports, computer
programs
Dramatic screenplays, stage plays, Sound CDs, audio
choreography recordings cassettes
Musical songs, music as distinct Broadcasts television and
from lyrics or recording radio
of music broadcasts
Artistic paintings, drawings, Published books,
diagrams, cartoons, editions magazines,
photos, maps, sculpture newspapers
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.
Ermiyas W.
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.
Ermiyas W.
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
Übersicht
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.
Ermiyas W.
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.
Ermiyas W.
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
Ermiyas W.
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 needs
before beginning to write. The primary audience of technical descriptions is often people who are
Ermiyas W.
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.
Ermiyas W.
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.
Ermiyas W.
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.
Ermiyas W.
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 sources need to be acknowledged, and if
there is enough material used directly, copyright
permission needs to be sought.
Creating content
More often, the ideas and words may derive more

generally from research, or they may be related
directly to the new system, process or product
that has been created and which needs to be
described.
References
Listing sources for material
in technical documentation
is important. This might also
be done by cross references
or links to information
elsewhere that the reader
may need.
Copyright
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.

 Plan your document and create an outline
 Know you audience
 Be prepared with references and non-text components
 Begin a first draft.
Ermiyas W.
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.
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.
Ermiyas W.
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.
Ermiyas W.
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 several
lines.
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.
Ermiyas W.
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 source
that provides power to a server or workstation or other device
Ermiyas W.
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
Ermiyas W.
(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 use.
sneakernet 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
Ermiyas W.
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.
Ermiyas W.
Stage process tasks

Substantive Substantive or Editor liaises with other team members, such as a
edit structural editing designer or on-screen publishing specialist.
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 publisher.
Copy edit improve Editor liaises with other team members, such as a
meaning and designer or on-screen publishing specialist.
presentation and
to query content. Changes are taken in and any substantive or copy editing
task made necessary by changes are repeated.
Copy is provided In word processing applications templates can be
Formatting for formatting designed to convert or carry across formatting to page
and for print and on- layout programs or on-screen mark-up languages (such as
programming screen. XML or HTML); formatting to a template will often 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
Proofread incorporate (when pagination is set), cross-references to page
formatted corrections numbers and the table of contents listings can be checked
copy of The formatted and corrected. An index is commissioned or created at
paper-based document (called this stage.
version first proofs) is If further changes are made at this stage, necessary editing
checked against and proofreading tasks are repeated. Versions of marked
the manuscript. up and printed documents are then proofed again
(versions called second proofs and so on, until ready to be
signed off for print)
Printers Check proofs Sample bound pages and covers from the printer are
proofs given a final check. Sign off for printing.
Proofread Check screen Any necessary changes are identified. If changes to screen
formatted layout, layout and functions are requested, repeat any necessary
copy of on- navigation, editing of proofreading tasks.
screen labelling and Proofread corrected (and otherwise changed) screens.
version metadata Sign off for replication (to CD).
The focus of editing tasks
Structural integrity
In a longer document, the editor (and Elements

later, the proofreader) checks the  Cover
Ermiyas W.
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 make
 Table of contents
sure that it accomplishes what it
should, and that all the necessary  List of tables and figures or
information and elements are both
supplied.
 Abstract or executive
The list opposite is a likely order of summary
pages for print materials, while
depending on the document, the exact  Preface
order and the number of elements will  Glossary
be chosen to suit content. Some
similar elements might exist in  Page numbers
onscreen versions, where preliminary  Page numbers
pages will be home pages linked to
other screens.  Headers and footers
Page references in the various sections  Graphics
and for the table of contents would
also be inserted, checked and  Section dividers/tabs
corrected by the editor, and then
 Electronic links
checked again by a proofreader. The
editor would spot check page  Appendixes
references in the index for accuracy,
 Attachments
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
Ermiyas W.
 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).
Ermiyas W.
 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

Ermiyas W.
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).
Ermiyas W.
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

Ermiyas W.
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
Ermiyas W.
Select Start | Control Panel
Figure C
Ermiyas W.
Left click Advanced system settings — Left click Continue if prompted by the UAC (User
Account Control)
Figure D
Ermiyas W.
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
Ermiyas W.
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

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

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

Ermiyas W.
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.
Ermiyas W.
#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
Ermiyas W.
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.
Ermiyas W.
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.
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.
Ermiyas W.
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
Ermiyas W.
 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

Ermiyas W.
Phase Activity Related approvals

Planning Project initiation Feasibility report approval
Content The determination of the Approval of scope
specification scope of client document and publishing
requirements and the scope schedule or timeline
of work
Implementation Development completion Approval of technical review
Production and Design completions Client validation and
evaluation approval of technical
documentation structure
Completion of Review and user testing
documentation 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 page Graphics
(ISBN or ISSN or both,
copyright statement)
Acknowledgements Section dividers/tabs
Table of contents Electronic links
List of tables and figures or Appendixes
both
Abstract or executive summary Attachments
Preface References/bibliography
Glossary Works cited

Page numbers Index
Ermiyas W.
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.
Ermiyas W.
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?
Ermiyas W.
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
Ermiyas W.
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.
Ermiyas W.
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.
Ermiyas W.
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.
Ermiyas W.

Creating Technical Documentation TTLM Final

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Creating Technical Documentation TTLM Final

Uploaded by

Copyright:

Available Formats

Ethiopian TVET System Entoto TVET College

HARDWARE AND NETWORK SERVICING

Unit of Competence: Creating Technical Documentation

LO1: IDENTIFY AND ANALYZE DOCUMENTATION NEEDS

Inside this reading

Technical documentation basics 3

Working out what is required 6

Technical documentation basics

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

Table 1: Version control table

Date Produced by Reviewer Editor Version

Table 2: Configuration management example

Item Location Responsibility

Table 3: Baseline control

Name Signature Date

Defining the scope of work

Working out what is required

From broad questions to details

To start gathering requirements you first need to ask broad questions:

Table 4: Categories of requirements

business case for can manage information and support the

Supportable? Can the requirement be supported in the documentation

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

Is there anything missing? Better to have stakeholders

Are there conflicts with any other requirement, or other

Is the requirement simple, short and to the point?

Can other people readily find and identify this requirement,

Reviewing requirements to come up with specifications

worded to make more than one interpretation virtually impossible.

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

the specific objectives of the contract.

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

deals with specific SOW language.)

Scope of Work Format

IV. Requirements include schedules

Design technical documentation

Inside this reading

What is the technical information required to do? 15

The use of templates 22

Structure and navigation 25

Digital document design 31

What is the technical information required to do?

A good technical document:

Content distribution—what goes where

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

The advantages of using a style guide

Style guides used together with templates (discussed next) can:

The use of templates

Formatting and templates

 automatic table of contents generation.

Structure and navigation

Search and reference features

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

across documents quickly know how to use that document.

Structural ordering of traditional and longer documents

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

Information type Best presentation method