With the abundance of information, technical writing has become an important job function everywhere. People want to get useful information but they want to get them conveniently and effectively. Nowadays, people are also flooded with information. Put yourself in the customer's shoe. There are plenty of good information. Why should one chose to read your paper in particular? It is then not just how to provide the information, but also how to interest people.
Technical Writing in English is far more than just English grammar taught in schools in the past. It is also more than just providing useful information.
Technical writing is not just about English.
It deals with
Always keep in mind that the purpose of your document is to draw the attention of the readers, to interest them, and to convince them about your technical information. Most guidelines taught in school about English writing applies to technical writing. Yet they are not sufficient. Technical writing requires certain different emphases to enable people to read with ease of understanding and interest. Even some writing practices acceptable for non-technical writing in the past may no longer apply.
Ease of understanding from the readers' perspective is the key in technical writing. The contents of technical materials are usually already complicated enough for the reader to understand. The readers will be lost if you burden them further with complicated English.
The first major task in technical writing is NOT to write, but to organize your thoughts. This is really a very major task. One way is to write out your thoughts in a presentation format (PowerPoint). Always keep your audience in mind when you put them in presentation format. Order your thoughts within each slide and from slide to slide. Within each slide, there may be one major thought that consists of a list of points. Connect these points to each other in a logical flow: one point leads to or flows to the next, but does not rely on knowledge from future points.
Many engineering students find it too much of a task to organize the thoughts. Well in business perspective, we serve our customers. Your customers are the readers of your document. These customers have plenty of other things to read in this Information Age, but they have chosen (or you are trying to convince them) to read your document! They are not reading your document for the sake of reading English but are trying to figure out what are the interesting things you are telling them. If you don't organize your thoughts, you will be forcing your readers (customers) to go through this difficult task themselves. If you find it difficult to organize your own thoughts, wouldn't it be more difficult for your readers? If these customers have to struggle through your unorganized thoughts, they certainly will not enjoy and will likely give up reading your document.
Note that school children may have already been taught to begin writing by first listing and organizing the points. As they mature in writing, many find that they don't need to make the list any more. That is probably because most people only learn to write non-technical English. In writing a "short" story, for example, the chronological order of the events is already a good way to order those events.
A poorly organized paper or thesis often results from the writer's lack of thorough understanding of the materials. Trying to produce the research output (paper or thesis) without thorough understanding will result in a poor paper. It does not mean you cannot begin the paper until you have completed the research. Instead of writing the paper or thesis, work on the figures, tables, and organize them in the presentation slides. Organizing the thoughts during research helps you to better understand the research. It also helps you identify the gaps in your research.
A very good practice to organize your thoughts is to:
In most articles, a general rule is not to exceed 3 major points, because most readers cannot struggle with more than 3 major points. Yet in a technical document, there may be tenths of points especially when you don't organize them. These points need to be linked together, such as in a tree or in a table. There may be only one main theme (the title of your document), which is supported by a few major points. The rest of the points are details under these major points. Some may be linked in the form of a family tree. Others may be related to each other in a table, which is good to show a 2-dimensional relationship.
See also Writing Technical Articles
Return to technical writing menu
Example:
What is most important to remember from all of these is that the
primary goal is reduced cost of the system.
Rewrite as
The primary goal is to reduce the cost of the system.
Example:
Wireless networks are important in rural areas because wireline
infrastructure is not needed because the schools in these areas
need Internet access but the wireline infrastructure is difficult
to install there when they are remote locations through in hilly
terrain.
Rewrite as:
Wireless networks are important for rural areas because wireline
infrastructure is not needed. The schools in these areas need
Internet access. The wireline infrastructure is difficult to
install there when they are in hilly terrain.
(This is not yet okay. See below.)
Example:
Wireless networks are important for rural areas. The wireline
infrastructure is not needed. The schools in these areas need to
Internet access. The wireline infrastructure is difficult to
install there. These areas are in remote locations through hilly
terrain.
A list of short and separate sentences is conveying a long list of separate points to the reader. The resulting lack of organization (linkage) is difficult to understand.
Example:
Internet access is needed for the schools in rural areas. Yet
wireline infrastructure is difficult to reach especially to remote
locations through hilly terrain. Wireless networks, which do not
need wireline infrastructure, has therefore become useful for
these areas.
Connective words also convey the links of the thoughts.
A paragraph contains only one major thought, which may be a train of thoughts linked together. The different sentences in the same paragraph are therefore organized and linked together.
To start a new paragraph signals the conclusion of the train of thoughts in the previous paragraph. The next paragraph will then begin the next train of thought. Different paragraphs under the same heading are linked together to the major thought of the heading. Yet the link between different paragraphs are weaker than the link within a pragraph.
The different heading levels and the paragraphs are used to structure the relationship of the thoughts into a hierarchical tree.
Within each heading, pause after each paragraph and ask what is the major point you have conveyed in that paragraph and does the text really conveyed that? Also ask yourself how does this link to the next thought in the next paragraph.
Avoid long paragraphes. With a technical document, people cannot understand so many pieces of information in one single paragraph.
Analyze the thoughts in the same way within each major heading. As you repeat over the different levels of headings, you can check how the thoughts are structured like a family tree. Careful think through the relationship of this family tree. Also bear in mind the chronological order to read your document. Feel free to re-order if you can improve the relationship. Today, the use of computer to write documents with headings have made it convenient to change the structure.
Return to technical writing menu
Example:
Alexander Bell invented the telephone.
Telephone was invented by Alexander Bell.
Chose the former especially when there is not much difference in
meaning. Chose the later only when you really want to emphasize
the Telephone, such as:
Telephone, which was invented by Alexander Bell, had started an
era of telecommunication.
Example:
The computer failed when the humity was too high.
The computer fails when the humity is too high.
The exeption is when you really need to tell the reader that it
happened in the past:
The computer did not work because the humity was too high
yesterday.
Example:
To describe the setup of your experiment, you may say:
A wire connects between the two boxes.
To describe what you did yesterday to set up the experiment, you
would say
A wire was connected between the two boxes.
Yet even when you are reporting an experiment you perform yesterday, it often does not hurt to describe the setup instead using present tense.
Whenever possible, choose the former.
The above facts are despite the practice of using the past sense and passive voice in the past to write experimental reports in schools. Most technical papers are using present tense today. Instead of telling people what you did in the past, you can usually talk instead about the process you had invented or used. The description of this process may then be in present tense.
Example:
The telephone was invented to enable communication over long
distances. The acoustic waves of the voice was first converted to
electromagnetic waves, which were then amplified and transmitted,
etc.
The telephone is an important invention to enable communication
over long distances. The acoustic waves of the voice is first
converted to electromagnetic waves, which are then amplified and
transmitted, etc.
Example:
As network connection is not available in the office, the staff is
using wireless modem.
The reader will first read the word "as" but will then have to defer its interpretation until after reading the rest of the sentence to understand in what context "as" is used. Eventually, the reader will figure it out. Note that this "slight" struggle of the reader is acceptable in non-technical English. Yet in technical writing, one tries to relieve the reader from such burden by using the word with the single meaning that the writer intends:
Because network connection is not available in the office, the
engineer is using wireless modem.
or
While network connection is not yet available in the office, the
engineer has been using wireless modem.
or
Whenever network connection is not available in the office, the
engineer uses wireless modem.
(except when you need to put a different emphasis)
Example: the noun conservation is derived from the verb converse
We teach people conservation of energy.
We teach people to conserve energy.
Example:
Can you explain the usage of this computer?
Can you explain how to use this computer?
Example:
Put linkages to your thoughts.
Link your thoughts.
Example:
The instructions are not unknown.
The instructions are known.
Example:
This is not a bad idea!
This is a good idea!
Example
The computer is running very hot.
Although this may be acceptable in non-technical writing, a
statement which is open to interpretation conveys no precise
information needed in technical writing.
Rewrite as:
The computer is running at a high temperature of 60C.
Example
With this new process, the computer speed has improved very much.
What is very much is open to interpretation.
Rewrite as:
With this new process, the computer has increased 30% in speed.
or simply
With this new process, the computer runs 30% faster.
Return to technical writing menu
The following usually have already been taught in schools, but are common problems in many senior and postgraduate thesis and drafts of technical papers submitted for publication:
Example:
high speed and processing power
It is not clear which of the following meaning is intended:
"high speed" and "processing power"
or
"high speed" and "high processing power"
rewrite as
processing power and high speed
or
high speed and high processing power
In the last sentence, even though use of repeative words is not
desirable in non-technical English, ease of understanding for the
reader in describing a complicated technology deserves more
emphasis. Nonetheless, the use of repeative words should be
avoided if possible:
high speed and large processing power
Example:
Is the limitation in the processing power or speed of the network?
Do you mean
"processing power" or "speed" of the network
or
"processing power" or "speed of the network"
Rewrite according to what you actually mean, such as:
Is the limitation in the processing power of the computer or in
the speed of the network?
or
Is the limitation of the network in its processing power or its
speed? (Both processing power and speed are referring to the
network in this case -- if that is what you really mean.)
An internetwork is one of many internetworks. You use it when
you refer to an internetwork for the first time.
The internetwork is one of many internetworks. It refers to the
one you have already refered to above.
Internet (with uppercase I) is the name of the global internetwork
being used today.
The confusion is an internetwork can also be abbreviated as
(lowercase) internet. So many students are making the same mistake
of using lowercase internet when they mean Internet. To avoid
confusion, I would rather always spell out the internetwork when
referring to it. I can then always use the upppercase Internet to
refer to the global internetwork we are using today. The other
experimental global internetwork will then be called Internet II.
Example:
The computer is fast and high temperature.
"fast" is an adjective, but "temperature" is a noun.
Gramatically, the sentence can be corrected as:
The computer is fast and hot.
or
The computer is operating at high speed and at high temperature.
Yet these 2 points being connected by "and" still do not have
the same structure in meaning. The author is making 2 points:
"The computer is fast" and "it operates at high temperature."
The computer being fast is a merit, whereas the computer being hot
can be a problem.
When ones reads a merit before the and, one expects to read
another merit after the and. The author should first clarify the
link between these 2 points and then use the appropriate
connective words to link them.
They will have different meaning and even different emphases
depending on how you link them:
The computer is fast but is hot.
Because the computer is running so fast that it is getting hot.
Example
limited information storage and processing overhead
There are many ways to interpret, such as:
"limited information storage" and "processing overhead"
"limited information storage" and "limited processing overhead"
"limited storage" and "limited overhead"
"limited storage" and "limited capacity to process overhead"
This is the same as for and/or.
Example:
Using the Internet,
search for papers,
e-mail,
Internet phone.
Rewrite as a list of actions one can perform using the Internet
Using the Internet, one may:
search for papers,
communicate using e-mails,
make Internet phone calls.
Or rewrite as a list tasks the Internet enables
Internet enables:
searching for papers,
communicating through e-mails,
making Internet phone calls.
Example:
With the Internet:
Rewrite as:
The Internet enables:
That and they must always refer to the subject under discussion.
Example:
A computer contains a lot of memory and it is expensive.
The "it" refers to the subject, i.e., the computer by default. You
cannot refer to the object without rewriting it:
A computer contains a lot of memory, which is expensive.
Example:
Most applications are using Internet Protocol. This enables
communication between different computers.
What is "this?"
Now the reader really needs to struggle. First, "this" refers to
the subject by default. Yet applications (plural) and this
(singular) do not match.
Then the reader looks at the object: Internet Protocol.
If you want to refer to the object, you could say:
Most applications are using Internet Protocol, which enables
communication between different computers.
Yet IP cannot enable communication. It is the use of IP that
enables communication.
If you want to refer to the action, you could say:
The use of Internet Protocol by most applications enables
communication between different computers.
Example:
The network is simpler because of limited routing information
storage and processing overhead.
Rewrite according to what you intend to say, such as:
The network is simpler because it requires less storage of routing
information and less overhead.
Example:
What is most important to remember from all of these is that the
primary goals are energy efficiency and reduced cost of the
system.
Although efficiency and cost are both nouns, they are not
parallel in structure. What are parallel may be:
"increase in energy efficiency" and "reduction in cost"
Rewrite according to what you intend to say:
The primary goals are to improve energy efficiency and to reduce
the cost of the system.
Return to technical writing menu
The most common paper references are in the following form (note
the exact punctuations very carefully):
First author, second author, and third author, "Title of paper
plus common at end of title are enclosed by double quotes,"
Name of book such as IEEE Transactions on so and so or
Proceedings of the International Conference on so and so is in
Italic, Volume number, Name of publisher if it is a book,
Name of city where the conference was held or the city of the
publisher of a book, Date of the conference or date of the Journal
or book, page numbers.
Note the "and" before the name of the last author.
Note the , after the name of each author. The only exception to
omit the , after the first author is when there are exactly 2
authors.
Note the closing " is after the , at the end of the title.
Not the following:
"Title of paper", (" should be after ,)
"Title of paper,", (no more , after ")
See also
Written Technical Communication
Return to technical writing menu