Documente Academic
Documente Profesional
Documente Cultură
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.
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
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.
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.
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.
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.
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.
2.) Contract
This is a formal agreement between two or more persons; organization or parties to do
something on mutually agreed terms.
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
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.
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.
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.
15.) Specification
This contains detailed information about performance courses, materials for construction,
theory of operations, sample calculations, table and operating data and information.
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.
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!
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:
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):
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.
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.
12
BODY headings and sub-headings which
reflect the contents of each section
13