Тулегенова
Карлыгаш Тулегеновна
Академический инновационный университет, Казахстан
The Nature of Technical Documentation
In an attempt to clarify the
nature of technical writing and what is actually produced, it would be useful
to look at the general characteristics of technical documentation. Markel
(2003:7-10) provides a good general overview of technical documentation and its
production. To begin with, technical documentation always addresses specific
readers. Now we could argue that many non-technical documents are aimed at a
particular audience, but technical documents are more specific as regards the
audience they are aimed at than most documents. Technical documents are
produced taking into account the age profile, job, experience, knowledge,
seniority, tasks, problems, aims and objectives. The content, approach,
structure, level of detail, style, terminology etc. are all tailored to this
profile.
Markel says that technical
communication is not meant to express a writers creativity or to entertain readers;
it is intended to help readers learn or do something (2003:8).
The way in which technical
documentation is produced is also important, according to Markel, in defining
its nature. The very nature of the company, its culture, goals and
organisation, are reflected in the types of documents that company produces.
For example, a company with a rigid and formal hierarchy may tend to favour
formal and structured memos as a way of communicating between staff rather than
informal emails or a simple chat over a cup of coffee.
In producing technical
documentation, it is rare for just one person to be responsible for the entire
process. Technical communication is a collaborative process involving technical
writers, illustrators, editors, subject matter experts (SMEs; pronounced smee),
designers, illustrators, usability specialists and, of course, translators.
This is another important characteristic of technical documentation and it
illustrates its complexity. This complexity is also reflected in the tools used
in their production. Instead of being produced using a simple word processor,
many technical documents are produced using high-end desktop publishing
packages and are disseminated via the web in formats such as PDF, HTML and
Flash; electronically distributed documentation can even contain animations.
All of this makes technical
documents more than just printed text on paper. They make the documents more
effective and flexible but they require translators to master many of the tools
used in to create the documents in the first place.
Another, more immediately
obvious characteristic of technical documentation is the way it uses design to
improve the appearance and readability of documents. By manipulating the design
and layout of a document, we can make it easier for readers to navigate through
the document and find the information they need as well as making it easier to
understand. As part of this design process, technical documents will often
contain a combination of text and graphics to make the document more
stimulating and to communicate and reinforce potentially difficult concepts and
processes. Graphics in a document make it possible to communicate large amounts
of information often regarded quickly and clearly and their presence in
technical documents is as essential.
We can categorise technical
publications as follows:
·
Procedural documents such as assembly instructions, instructions for
operation etc.
·
Descriptive and explanatory documents such as descriptions of products
and services; explanations of processes, concepts etc.; progress reports.
·
Persuasive or evaluative documents such as research proposals or
engineering projects, product or service evaluations as well as reports
recommending actions or policies
·
Investigative documents such as reports which are intended to present
new knowledge etc.
The first two categories are
of most interest to us here because they relate directly to the subject of
software documentation of which the user guide is one type. This relationship
will be discussed in the following section.
Typical Technical Documents
Technical writers produce a
wide range of documentation in an enormous variety of subject areas and
industries. From gardening equipment and toys for children to aircraft
maintenance manuals, tutorials for word processors as well as ice cream makers
and nuclear submarines. The actual types of documents produced can vary
according to the subject, the nature of the product and the industry within
which the company operates. However, although the focus of this book is on
software documentation, or software user guides to be precise, we can identify
a number of typical documents that are frequently produced by technical writers
and translated by technical translators.
Documentation
Documentation can be described
as the set of instructions shipped with a program or a piece of hardware
(Microsoft Press 1998). Houghton-Alico (1985:6) provides a more detailed
explanation when she defines documentation as:
...the collection of documents
that explain, describe, and define the purposes and uses of a particular
software program or a system made up of multiple programs.
Documentation generally
includes a variety of different documents such as system requirements, set-up
instructions, instructions for use, maintenance information etc. All of these
types of document can be classified under the following headings:
Technical
documentation
As its name suggests,
technical documentation provides detailed technical information relating to the
initiation, development and operational phases of the lifecycle of a software
product. Such information can include functional specifications, design
specifications, development procedures as well as test plans and analyses.
Technical documentation forms a written technical history of the product from
its inception and provides information necessary for the production of user
guides, project plans and maintenance (Houghton-Alico 1985:6-8).
Product
documentation
This type of documentation
provides information relating to product specifications, configuration and
set-up details, end-user maintenance and so on.
User
documentation
User documentation is intended
to help its readers to use the software in question. In addition, user
documentation provides information on other resources for users, explains
procedures, defines concepts and generally familiarises the reader with the
software and its use. User documentation includes among other things, user
guides, online help systems, audio-visual training materials, materials for
training courses etc.
Technical documents help
readers solve problems. As was mentioned earlier, reading technical
documentation is generally not an end in itself. People normally read technical
documentation because they want to be able to do something else, for example learn
how to use software or find out about the design details of a particular
device.
Bibliography
Markel, M. (2003).
Technical Communication. Sixth Edition. Boston & New York: Bedford/St.
Martins
Microsoft Press
(1998). The Microsoft Manual of Style for Technical Publications - Version 3.0.
[CD-ROM] Redmond, Washington: Microsoft Press
Houghton-Alico, D.
(1985). Creating Computer Software User Guides: From Manuals to Menus. New
York, USA and London, UK: McGraw-Hill