Ethiopian TVET-System

Database Administration
Level III

Learning Guide #
Unit of Competence: Create Technical documentation
Module Title: Creating Technical documentation
TTLM Code: EIS DBA3 04 0811

LO2: Design technical documentation

 Information sheet Design technical documentation
Introduction
Technical documents are used by technicians and engineers, project managers, manufacturers,
suppliers, software developers, systems analysts, and all communications and IT workers.

Effective technical documents don’t just happen; to be effective they are the result of a deliberate
and comprehensive design and production process. Although developers and writers vary the
steps they use to create a document, effective technical documentation design typically follows
well-proven general procedures.

Technical documents need excellent design and planning if they are going to do the job they are
meant to do. In this Learning Outcome you will be introduced to the requirements of good
technical document design.

Outcomes for this Learning Outcome

When you’ve finished this Learning Outcome you should be able to:

 Identify information requirements for technical documents.

 Break technical data into useable components.
 Develop the structure of the technical documentation giving focus to the flow of
information, style, tone and content format.
 Design document layout and structure.
 Create document templates and style guides.

Key terms
Design
Design is the act of working out the form and function of a thing. In this case it is working out the
form of technical documentation that is appropriate to its function.
Glossary
A glossary is a list of words used in a document and 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.
Index
An index has keywords, terms or names that are essential for users to find a subject or detail in a
document, or for people seeking that information to find your document on the web.
Information architecture
Information architecture describes the various aspects of structure for web sites where
information exists on different levels of the site, as well as across and between a series of pages
and pop-ups, with the design of the site determining the pathways or links by which that

Page 2 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
information is found, where it is placed and how it is displayed.
Metadata
Metadata is data about data or planning information about a document. Metadata provides
information about the content, quality, condition, and other characteristics of a document.
Style guide
Style guides list all manner of conventions to be used consistently to adhere to a corporate image
and consistent way of producing and presenting documentation. They are concerned with
editorial styles and standards that encompass all the elements of style, in the use of typography,
layout, word choice, spelling and punctuation (rules and precedents for which can be set out in
style sheets that accompany documents).
Style manual
Style manuals can contain much more comprehensive information that style guides, 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.
Template
A template is a document, 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.

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.

Figure 1: The place of design in creating technical documentation

Page 3 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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  designs
 reviews  reports
 records  Discussion.

A good technical document:

 meets a need
 serves an audience
 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.
Page 4 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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
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

Page 5 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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:
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.

Page 6 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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.

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.

Page 7 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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-up (verb) checksum help desk
CD-ROM desk check HTTPs host ID (two parts)
coordinate dial-up ID (no need to spell-out)
copyfree downtime ipconfig and ipconfig/all (lower case)
copyleft flow chart

JKL MNO PQR

loopback (n/adj) NetBIOS net ID (two read-me (files/docs) re-use psuedocode
loop back (verb) parts) onscreen practise (verb/transitive)
practice (noun/adjectival)

STU VWX
subnet and subnetting Web web site (two words)
sub-layer time frame (two words) workstation
time line (two words) walkthroughs (one word)

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

Page 8 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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.
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:

Page 9 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
  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
 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
Page 10 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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, 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.

Page 11 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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 page
and hyperlinks 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 documents
consistency across within an organisation the same; users then quickly know how to
documents use that document.
Integrated graphics Graphics help interaction with readers and users. 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

Page 12 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
  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.
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.

Page 13 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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
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
Page 14 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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.

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
Page 15 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
(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:
 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).

Page 16 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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 outcomeage 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 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,

Page 17 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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.
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
Page 18 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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.
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:

Page 19 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
  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.

What is protected by copyright?

The Copyright 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

Literary novels, poems, song lyrics, Cinematograph films, videos,

newspaper and journal films DVDs, Flash
articles, essays, reports, animations
computer programs
Dramati screenplays, stage plays, Sound recordings CDs, audio
c choreography cassettes
Musical songs, music as distinct from Broadcasts television and
lyrics or recording of music radio broadcasts
Artistic paintings, drawings, diagrams, Published editions books, magazines,
cartoons, photos, maps, newspapers
sculpture

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.

Page 20 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
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.
.
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.

Page 21 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
Self check

1. For what purposes might you design technical documents at work?.

2. Define a technical document?

3. What is a style guide?

4. What is the difference between a style guide and a style sheet?

5. What might the ‘body matter’ section of a longer technical document include?
6. Exact and ambiguous access schemes are:
A. Categories of information architecture
B. General ways of organising onscreen documents so that they can be searched and
used
C. The way documents are physically delivered to technical users
D. Good and bad plans for the structure of documents onscreen and in print.

7. Where would you find metadata about a technical document on a web page?

8. How is copyright created and how long does copyright last?

Page 22 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
Answer to self check
1. you might be designing documents to:
 develop new software applications
 control a major project
 manufacture new products
 maintain equipment
 explain operating policies and procedures
2. A technical document is an object that is necessary to operate, maintain, repair, support or
dispose of a system or equipment throughout its life. It may be in paper or electronic
format, and in a range of media.
3. A style guide is a reference document used in an organisation to guide the writing style and
presentation of documentation, and to ensure consistency and a common corporate image
across a range of documents.

4.

 A style guide specifies details of writing and presentation style, often for a
particular organisation (a house style), and includes guidance in such matters as
punctuation, capitalisation, and rules for spelling and usage, as well as the ways in
which materials are to be produced.

 Style sheets for documents accompany individual documents and are a record of
all decisions made for that document.

 A style sheet can also be a set of formatting commands for a template that are
kept separate from the actual content being formatted, such as with Cascading
Style Sheets (CSS), a feature applied to web pages to ensure consistency of
features on a web site.

5. The body matter of a document includes the chapters or sections of the document. Each
chapter or section should start with a heading and a summary of the other main headings in
the section. In online documents cross references between sections are made with
hyperlinks. Appendices such as tables, or raw data or other sets of technical information
that help the reader understand complex information can also be placed in the main section
of a longer technical document (though they are also often included as end matter).

6. B

Page 23 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu
 7. Metadata provides information about the content, quality, condition, and other
characteristics of data: on a web page, the metadata is found in the Head section of the
HTML code.
8. Copyright comes into effect 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. 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.

Page 24 of 24 Author: Bishoftu ICT Dept DBA/ Level III Date Sept 2020
Bishoftu