Sie sind auf Seite 1von 13

Nature of Technical Writing

Introduction
Technical writing introduce you to some of the most important aspects of writing in the
world of science, technology, and business—in other words, the kind of writing that
scientists, nurses, doctors, computer specialists, government officials, engineers, and
other such people do as a part of their regular work.
To learn how to write effectively for the world of work, you'll study common types of
reports, special format items such as lists and headings, simple techniques for putting
graphics into reports, and some techniques for producing professional-looking final copy.
However, the focus for technical writing is not necessarily career as a technical writer but
an introduction to the kinds of writing skills you need in practically any technically oriented
professional job. No matter what sort of professional work you do, you're likely to do lots
of writing—and much of it technical in nature. The more you know about some basic
technical-writing skills, which are covered in this guide and in technical-writing courses,
the better job of writing you're likely to do. And that will be good for the projects you work
on, for the organizations you work in, and—most of all—good for you and your career.

Characteristics of Technical Writing


Technical writing presents and explains a subject matter in a clear, objective, accurate,
concise, and unemotional manner.
Technical writing uses a relatively high concentration of certain complex and important
writing techniques particularly description of a mechanism, description of process,
clarification, cause and effect, comparison and contrast, analogy and interpretation.
Technical writing highly utilizes technical vocabulary. It utilizes tables, graphs and figures
to clarify and support textual discussion. It uses the conventional report forms.

Purpose of Technical Writing

The following are the primary purposes of technical writing.


1. To inform
It is written to make another person understand or to do something. It is designed to
fulfill a need to tell and a need to know.
2. To analyze events and their implications
It will explain how certain systems failed. This system may include education,
socioeconomic, political and the needed change.
3. To persuade and influence decisions
It will show how a business or an industry succeeds.

Technical writing is ideally characterized by the maintenance of impartiality and


objectivity, by extreme care to convey information accurately and concisely and by the
absence of any attempt to arouse emotions.

Functions of Technical Writing


1. To serve as a basis for management decision
2. To furnish needed information.
3. To give instructions
4. To explain techniques
5. To report achievements
6. To analyze problem areas
7. To determine design and system requirements
8. To serve as a basis for public relation

1
9. To provide report to stockholders of companies
10. To develop a product
11. To provide service
12. To record business through proposals
13. To procure business through proposals

Basic Principles of Good Technical Writing


1. Understanding the reader
2. Knowing the purpose of each article or report
3. Knowing the subject matter
4. Writing objectively
5. Using correct format
6. Adopting ethical standards

Understanding the Reader


A basic consideration in technical writing is to know the target audience. The technical
writer should know how to adapt his writings and terminologies of the type of the intended
audience or readers. Difficult technical terms used must be carefully defined so that the
reader will easily understand the information being presented. If the reader fails to
understand what he reads, the writer fails in his mission. The technical writers should
know how important his readers are. The target readers help the writer to know what to
write about and how to write it.

Knowing the Purpose of Each Technical Report


The technical paper must be organized around a central theme. The reader should
understand the main purpose after reading the paper. The purpose maybe is to describe
a thing, to report on a specific problem or project, or to analyze and solve a problem.

Knowing the Subject Matter


A technical writer must have a thorough knowledge of the subject he is to write about. If
the report is on the result of a technical experiment, the writer who writes the report should
explain what the problem is all about, what causes the problem and how the problem is
solved.

Writing Objectively
A good technical writer must emphasize the facts and the data. The impersonal style is
basic to an effective technical writer. He represents facts, figures and statistics skillfully
woven around the subject matter or central theme and written in an impersonal manner.

Using Correct Format


The format and style of a report attract the attention of the readers first. Companies
require neatly-typed communications, reports and project proposals and feasibility
studies. The current trends require that such communication be computerized or typed.

Adopting Ethical Standards


A technical writer should undertake comprehensive research work; accumulate the
required data through interviews, surveys, referrals and related publications. He must
have to present facts and figures as gathered and required, using only those that are
pertinent to the report. A good technical writer also acknowledges the help he receives
from others and cities sources of reference materials.

2
Styles in Technical Writing
Style is the writer’s way of writing, a manner in which he expresses his thoughts and
feelings in a language. Below are guidelines for clear technical writing.
1. Be selective, focus on the essential information and the significant details.
2. Develop a clean, direct style; avoid inflated language and scrambling sentences.
3. Use examples and comparisons to clarify descriptions and explanations.
4. Repeat words and phrases for clarify or emphasis or to ease transitions, but avoid
needless repetitions.
5. Delete unnecessary words and phrases, but avoid short cuts that sacrifice meaning.

Sentence Structure and Length


Technical writing should use the natural word order, simple sentence structure and good
short sentences. Since technical subject matter requires the use of complex, technical
vocabulary and the expression of complex ideas, the use of shorter words and sentences,
simple in structures, will help a lot in the readability of difficulty material.

Paragraph Structure and Length


In technical writing, the topic sentence should come first in the paragraph or at the very
latest part after whatever transitional sentences appear. Sometimes the writer does the
opposite by giving the details at the beginning and then concludes by stating the main
idea. The use of one or more very short paragraphs achieves an especially forceful effect.

Scientific Attitude
Judicious weighing of evidence is very important in a technical report. The best evidence
is one which is the most ample, the most pertinent and the simplest in explaining the facts
with the least additional evidence and most in harmony with the rest of the available
evidence. The conclusion or recommendation should include all evidences in which the
judgement is made.
The technical writer must know when he would say enough, and not overwrite. As a writer
of his materials, he should know what to present, what to amplify, what to rewrite and
what to emphasize.

Generalization
When the technical writer makes generalizations, he is giving probable conclusions
derived from the observation of factors. Since the report is based on generalizations, it is
necessary to describe the circumstances surrounding the report. Provide enough
evidence, data and samples to enable the reader to evaluate the generalizations for
himself.
To be certain that you have followed ground rules and not “Jumping to conclusions”, test
the validity of your data and samples. Here is the suggested checklist (Nem Singh and
Calixihan 1994)
1. Can I prove its accuracy?
2. Can I show the direct bond between the facts and generalizations?
3. Is it fact and not opinion?
4. Do I have all the facts?
5. Are they up to date?
6. Is the generalization verifiable? Would I get the same result it I do it again?
7. Is it significant?

The principles to be observed in organizing the material as cited by Alvarez (1980) are as
follows:
1. To organize the material of a subject, first break it down into the component aspects.

3
2. To organize a report or paper, choose a suitable approach and make an outline that
implements it.
3. The basic unit of organization is the paragraph.
4. Use these paragraphs to present related data, graphs to show trends and visual to
clarify description.
5. Plan a report or paper thoroughly before starting to write it.
6. Gather the necessary data through basic library research and primary services.
7. Write a first draft.
8. Revise and rewrite as often as necessary
9. Write a final draft
10. Place footnotes to acknowledge references and include a bibliography at the end of a
report or paper.

Other attributes of good technical report writing are:


1. appropriateness
2. functional
3. informative
4. factual
5. efficient
6. correct

The Technical Writer

The Role of the Technical Writer


A good technical writer possesses insights, perceptiveness, quick to determine
probabilities and the ability to adapt to requirements. He can identify developments that
may affect his project.

The technical writer must understand the nature of his work. He should be able to help
his principals attain the target objectives. He must not only possess the technical writing
ability and technical expertise, he must also have the capability to grasp, analyze and
interpret unexpected events and situations that occurred during the writing of the technical
report.

The technical writer should have the ability to state facts clearly and accurately to organize
a variety of elements into a unified structure, and to describe logical generalizations.

Hallmarks of an Effective Technical Writer


The hallmarks of an effective technical writer is represented by this acronym REPORTER
(Mosura and Tenorio, 1999)

R - Resourceful
E - Energetic
P - Patient
O - Observant
R - Responsible
T - Trustworthy
E - Evaluative
R - Responsive

4
Guide to Effective Technical Writing

For effective technical writing, the ABC’s of report writing given by (Zall 1980) can be
considered in-depth.

Accuracy
A report writer must be tactful in the recording of data, statement or calculating
mathematical figures. He must check every statement in its final form. An error committed
and an illogical statement written can create confusion as well as doubts over the whole
text. A writer should always aim to be understood.
Brevity
Being brief is a courtesy to the reader. The reader should find it easy to group the main
idea of the report. In the same manner, accuracy of the statements can easily be
maintained. The reader can get the essence of your thinking in a compressed form.
Confidence
A good report writer must have the quality of self-confidence. He cannot only
communicate but he has to be also decisive or sure of what he is writing about. After
finishing the last page of his report, he is an authority.
Dignity
Dignity is courtesy to your readers as professionals. This is an ethical standard. The writer
must be certain that all grammatical constructions are correct. In report writing, you need
to be formal with words and how these words are used. You should be sure that the ideas
or information are well organized, simplified, summarized and expressed in
straightforward manner.
Facility
This refers to the devices used by the writer, to make his report easy to read and
understand. In most cases, report writing depends more on pacing, sequence,
arrangement and continuity of ideas as well as information. A grammatical correction is
important. He should make his writing straightforward, logical and clear. The thought from
one part to another should be clearly established, illustrated or stated.
Emphasis
The writer has to feel what is important to the reader and should never expect how the
reader finds it out for himself. He has to lead him from point to point, clearly marking every
step, directs the reader to the right way and gives him the reason for stopping at a
particular portion.
Honesty
Honesty is expected in a report. When a writer has borrowed some statements, ideas or
quotations, he has to acknowledge them either in footnotes, endnotes or cite the source
or author of the borrowed ideas or statements within the running text.
Illustration
Illustration materials such as charts, graphs, diagram and photos are always helpful. The
writer should use them to clarify and support the text. They can be used to show situations
or trend or movement.
Judgment
The writer should qualify the date and information gathered by judicious weighing. This
can be done by the following these criteria:
1. Most ample
2. Most pertinent or relevant
3. The simplest in explaining the facts with the least additional evidence
4. Most harmonious with the rest of the data and information.
In every case, the evidence used as a basis of judgement (as in conclusions and
recommendations) should be included in the report.

5
Knowledge
The communication of knowledge is the primary objective of the report, but knowledge is
not only a collection of data or information. It involves interpretation and information of
conclusions. With out sound interpretation, the data will become useless.
Logic
Logic is chiefly a process or classification. It is putting things in their proper places. It
shows the relations among groups of things and classes of groups. By thinking logically,
one can avoid the following trouble areas:
1. Statements must not contradict each other.
2. Words must be used in consistent sense
3. Statements must move in one direction whether space, time or relation.
4. Statements must make sense.
5. Judgments must not be based on few data.
6. Cause and effect should be clearly distinguished from simple sequence.
7. Conclusions should not be inferred if they have no connections with the data.
8. An authority should not be accepted if he is biased or he is not an expert in the
particular field.
Mechanical Neatness
This is the general appearance of the report. It must be neatly encoded or typed, properly
margined, free from typographical errors, erasures crossing-outs and smudges.
Headings and subheadings and indentions are mechanical devices, which help make the
organization of the content clear.
Normal Procedure
The report is easier to understand if it conforms to the standards practices. The writer
must follow the acceptable arrangement of the different parts of a report. If the writer
deviates from the normal procedure, he should inform his readers by explaining his
reasons for doing it.
Objectivity
In technical writing, the writer should consider himself as another person, uninterested
observer or an innocent bystander. In this instance, the third person point of view is
preferred. The writer should treat his subject matter the way he sees or observes
it. Technical reports avoid the use of the first person (I, me, my).
Planning
This is primary in all activities. This gives the purpose and directions to what the technical
writer has to write. This involves thinking ahead of what one has to do, when to do it and
who is to do it. This will be reflected in a well-organized report.
Qualification
The technical writer should select only those statements that have direct relationship with
the topic being discussed. The writer should evaluate the ideas or statements he will
include in the writing of the report.
Revision
This consists of more than merely correcting the spelling, punctuations, spacing and
margin errors. The writer must also check every statement for sense and relevance and
be sure that he has said all that must be said. An effective report is all that is require to
perfection. The secret of good writing is rewriting.
Straight Sentences
Sentences carry the full weight of the meaning in a report. The sentence to be employed
must be limited to only one idea or to closely related ideas. To avoid monotony, vary your
sentence structure and employ appropriate transitional devices. By employing such
devices, there will be a smooth transition from sentence to sentence. They will show the
readers the writer’s thoughts leading him to what the writer wants to communicate.
Thoroughness
The writer should treat well his subject matter. The writer should check the thoroughness
of his report from initial thinking to final submission. The writer is obliged to go over the

6
subject, analyze and investigate it, organize and interpret the results and draw
conclusions whether it is positive or negative.
Unity
A report is unified when everything is clearly relevant to the main point under discussion.
Nothing should be left hanging. No question should be left unanswered. After all, the main
objective of a unified report is to let the readers feel that they have read everything
essential to the subject undertaken.
Viewpoint
A report is written from a certain viewpoint: that of a reporter, proponent, researcher or
an author. The viewpoint is established in the first sentence and should be maintained
consistently throughout the report. Voice unity should also be observed.
Word Choice
The writer should choose the words that are fit to the reader’s understanding. Avoid words
which are difficult to understand.
Zest
Write only about things that are worth writing and which are invigorating. Write as though
you were performing a service that only you can perform.
Writing should not be regarded as something difficult but something that is enjoyable and
pleasurable.

The Important “End” Products of Technical Writing

1.) Technical Report


This provides useful information about a complete program of work, for reference and
permanent record.

2.) Contract
This is a formal agreement between two or more persons; organization or parties to do
something on mutually agreed terms.

3.) Feasibility Report


This represents facts and information intended to make the reader realize that the
proposed project or plan is financially, economically, and technically, significant as well
as beneficial.

4.) Business Letter


This is written communication or message used to transact business which cannot be
conveniently conducted orally.

5.) Brochure
This is pamphlet or printed information material given to a customer in order to convince
or persuade him to take action on the company’s services, ideas or products offered.

6.) Abstract
This is a summarized form of resume of a long piece of writing.

7.) Instructional Manual


This contains directions for work procedure or policies, or for the use of technical
equipment or appliances. Instruction relies on clear, specific, complete directions
presented in sequential order. Directions of complicated step-by-step procedures should
be accompanied by graphic illustration.

7
8.) Proposal
This contains suggestions for actions, usually involving change or performance. It may
be solve a problem, suggest a new project site, revise a policy or initiate a researcher
report project or terminate a project.

9.) Progress Report


This contains an account of what has been accomplished on a project over a specific
period of time and what may be expected in the next period.

10.) Policy
A plan of action adopted or preserved by an individual, government, party business and
industry or it may be a document containing a contract of insurance.

11.) Articles for a Technical Journal


A technical paper which will be published in a journal. It contains an abstract , an
introduction, discussion and summarizing, concluding sentence or paragraph.

12.) Monograph
This is a thorough textbook treatment which requires full illustration and documentation.

13.) Memorandum
This is an important form of written communication circulated within the company and its
branches which is used to disseminate a message or information.

14.) Graphic Aids


This refers to all pictures , graphs, diagrams and other materials used in illustrating
important details in a report.

15.) Specification
This contains detailed information about performance courses, materials for construction,
theory of operations, sample calculations, table and operating data and information.

16.) Printed Action Memo


This prepared form requires only a check mark in an appropriate square to indicate its
message.

17.) Survey Report


This is a thorough study of any subject. Some subjects of surveys are potential markets
fro products, labor policies, market punctuation, public opinions and community
resources. Examples are poll surveys on the study of a possible site for a new plant.

18. Trip Report


An account of a business or professional trip. It records specific and significant places,
events, conversations and people met. It attempts to answer where, when , what ,why
and how also. It may have recommendation section.

19.) Laboratory Report


A record of procedures and results of laboratory test. It describes the scope of a project,
the equipment utilized, the procedures used, the results of test and the conclusion and
recommendation.

8
20.) Technical Paper
A research paper written for a professional journal or magazine. Technical papers usually
describe a theory or new development. They assemble technical reports in the most
respects. The main difference lies on the fact that the audience for a technical paper is
wider and more diverse.

Steps in Technical Report and its Purpose

STEP 1 – PLAN
‘If you fail to plan, you plan to fail.’

All projects need to be planned – at least at some level. Whilst you don’t have to go create
a detailed Gantt chart for every technical writing project, it certainly helps if you answer
some of the following questions before you put pen to paper. The results of this planning
may be as simple as some bullet points jotted down in your notepad – or you may find
that simply going through this as a mental exercise is sufficient.

When you’re planning to write technical documents, you should ask yourself:

 Scope – How many documents do I need to write? What are their key
characteristics? Am I going to publish them in multiple formats – if so, are there
any production requirements I should be aware of?
 Timing – How long do I need to schedule for review cycles? What’s the final
deadline?
 Process – What are the high level steps that I need to follow to create the
documents?
 Along with these basic questions (which apply to almost any project – not just
technical writing) there are some specific writing-related questions that you’ll need
to consider in your documentation project:
 Audience – who am I writing for? Do they have a sophisticated command of
language? What are their education levels?
 Reviewers / Subject Matter Experts – these are the people who’ll lend their
technical expertise in the creation of the documents and review them for accuracy.

If you’re just writing one or two documents, you won’t need to spend much time on
detailed planning. However if you’re creating dozens, hundreds, or (heaven forbid),
thousands of documents, then putting some thought into these questions up-front will
save many a wasted hour later on.

Status Tracker
These templates are essential for more complex projects. Even simple projects can
benefit from a simple Status Tracker (in fact, that’s the one essential tool I use on every
single project).

STEP 2 – STRUCTURE
A structure is the backbone of your document – the hierarchy of headings that define the
logical order that it will progress. Structure is absolutely essential to successful
documents, and it’s something that you should develop before you start writing. A well-
structured document is one that has had thought go into it beforehand, which means
you’re less likely to need to rehash it later on.

It’s important to understand that structure isn’t a straightjacket – it’ll evolve and change
as you write and review the document. After you publish, you may end up with a very

9
different-looking document to the one you envisaged – that’s perfectly normal and there’s
nothing at all wrong with it!

There are a number of common structural approaches when it comes to technical


documents:

 Narrative structure – The traditional approach – intro, body, conclusion


 Process-based structure – Common in technical documentation such as
procedures and user guides
 Library structure – A collection of articles on a common topic, loosely structured
 System-based structure – Describing the components of a system such as an
auto manual

Whatever approach you choose, you’ll need to work with your subject matter experts to
understand how the structure you’ve developed will accomplish the purpose you’ve set
out to do – whether it’s explaining how a product works, how to carry out a procedure,
presenting information in a tender or sales document, and so on.

STEP 3 – WRITE
Writing is where you convert your bare-bones table of contents and notes into a series of
drafts, culminating in a draft that’s ready for formal review. Contrary to popular
impression, writing is only about 20-30% of the process in a well-planned document –
much of the effort goes into planning, structuring, and reviewing your work. In fact, the
more time you spend planning and structuring your work, the less time you’re likely to
spend on writing.

There are a few time-honoured (as well as some new) techniques that technical writers
draw on:

 KISS (Keep It Simple, Stupid!)


 Plain English
 Five Ws (and One H)
 Inverted pyramid
 Verb-noun structure
 Active voice

These techniques will help you write better documentation – documentation that your
audience finds useful, engaging and a pleasure to read. Of course, in order to apply these
techniques you need to have a decent grasp of the English language.

(Sidenote: Teaching you to write isn’t what a technical writing process – or my book,
Technical Writing Process – is about. There are plenty of resources available if you want
to improve your writing. The technical writing process is about is how to apply your writing
and project management skills to the task of producing high quality documents in a way
that hits the mark, resonates with your audience and achieves your deadlines.)

Writing well is one thing – but if you want to produce good documents, you’ll need to
engage your subject matter experts. If you’re a professional writer like me, you usually
rely on a subject matter expert – someone who’s an expert in a particular field – to lend
their technical expertise to whatever it is you’re writing about.

At this stage, engaging your subject matter experts means a lot of informal one-on-one
discussions – or even workshop-style if you have a large group of them. At this stage,
you should be asking your experts to contribute raw material, review and / or test what
you’ve written and so on. Remember – at this stage, it’s all fairly loose and informal – the
formality comes in the next step, Review.

10
The final part of writing is formatting and laying out your draft before you launch into the
formal review process.

STEP 4 – REVIEW
I like to think of review as the polishing stage. It’s where your document gets the trial by
fire, so to speak, of having others formally review it, as well as undergoing another very
important task – editing and proofing.

(Sidenote: Editing and proofing is in itself the topic of numerous books. In my book
Technical Writing Process, I’ve provided a practical, no-nonsense editing model – The
Seven Levels of Editing – that’s suitable for technical or business documents.)

If you haven’t already done so, you’ll now need to define who’s responsible for reviewing
what (also called a Review Matrix), or validating it if you’ve been proactive and defined it
during the planning step – which you should aim to do.

In the Review step, there are a number of discrete activities going on (depending on the
type of document being written):

1. Review by subject matter experts


2. Testing a procedure / instruction to make sure you / a subject matter expert can follow
the steps
3. Peer review by a colleague
4. Editing and proofing

The point of all these activities is to apply the appropriate level of quality control to ensure
your document is accurate, useful, usable, and so on – in other words, good enough to
publish. It’s not uncommon for documents to spend most of their time in the review step
– and by the end, they can be completely unrecognisable compared to how they started.

Review also involves an element of writing – documents will be reviewed, then revised.
High-profile documents – the ones where it really pays to put the effort in to making sure
they’re perfect – will be reviewed and revised many times before they’re ready to publish.

The final – and most crucial – aspect of review is sign off. This is the point where both
you – as the writer – and your reviewers are satisfied that your document is in a fit state
to be published to the world at large – whether that’s your team, company intranet, or the
entire world!

STEP 5 – PUBLISH
Publishing can be a complicated process – or it can be extremely easy. Publication is
where writers manufacture and launch the final product. This might be as straightforward
as emailing an approved document to your manager, or uploading it to a content
management system or intranet. On the other hand, it might involve some fairly
complicated logistics.

Technical Writing Process

By applying the steps, activities and tools in the technical writing process – and
customising it to suit your project – anyone with a sufficient level of writing skills can
successfully create technical documentation, or learn how.

11
Parts of a Report and Their Importance

The information provided in reports needs to be easy to find, and written in such a way
that the marker / reader / client can understand it. Reports utilize headings to divide
information into sections. The headings help the reader to locate relevant information
quickly. Below are some guidelines for structuring your report.

The structure of a report and the purpose and contents of each section is shown below.

TITLE PAGE report title


your name
submission date

EXECUTIVE SUMMARY overview of subject matter


methods of analysis
findings
recommendations

TABLE OF CONTENTS list of numbered sections in report


and their
page numbers

INTRODUCTION terms of reference


outline of report’s structure

12
BODY headings and sub-headings which
reflect the contents of each section

CONCLUSION states the major inferences that can


be drawn from the discussion

RECOMMENDATIONS indicates any further work that needs


to be done or identifies the
alternative you think best solves or
improves the problem

REFERENCE LIST list of reference material consulted


during research for report

APPENDIX information that supports your


analysis but is not essential to its
explanation

13