writing-skills.

com

The 7 most common mistakes in technical

writing – and how to fix them | Emphasis
Stan Carey
12–15 minutes

Most of us are technical writers at some point or other, even if we don’t realise it.

Contents
 1. Messy structure
 2. Too much jargon
 3. Poor punctuation
 4. Inconsistency
 5. Too much abstraction
 6. Unclear antecedents
 7. Dense presentation

You may be quite happy with the label if you write test reports or standard operating
procedures. But you can have a very different role and still sometimes need to write technical
things: a design brief, an employee handbook or even guidance on how to use the new office
photocopier. If your document is complex, and someone needs to be able to follow and act on
it, then it’s technical writing.

The fact that many people don’t realise that what they’re writing is technical may partly
explain why so many of these types of documents fall short. Fortunately, those shortcomings
tend to fall into just a few categories, and they’re easy to fix. So let’s look at some of the
most common difficulties technical writers (and their readers) face – and how to fix them.

1. Messy structure
Many technical documents confuse readers and fail to achieve their aims because they were
not planned properly to begin with. This lack of planning means that documents, especially
longer ones, end up structured in an illogical fashion. Things are hard to find in the text,
sections don’t follow naturally from each other, cross-references are a mess, and so on. At
best, this frustrates readers; at worst, it makes the document virtually unusable.

How to fix it:

Before you begin writing at all, think carefully about the overall layout of the document.
Creating a simple outline will help you structure it appropriately and optimally. So when
you’ve written the text, but before you publish it, have it carefully reviewed – preferably by
an editor or by a colleague who will read it closely. They may suggest improvements to the
document’s structure, especially if you ask them to keep this in mind. The structure of the
finished document should seem logical and intuitive to its intended readers.

2. Too much jargon

Who your readers are will inform the content and style of your text. So it’s important to keep
them in mind throughout the writing process. If you’re writing something for specialist
readers, some jargon and technical language is fine; it may even be essential. If you’re
writing for a general audience or people who actually specialise in a different area, be careful
– what’s familiar and self-evident to you may not be so to them. One manager who
commissioned a technical-writing course from Emphasis described how different specialists
may ‘talk different languages’. You need to ensure that nothing gets lost in translation.

How to fix it:

Take a few moments to identify and visualise your readers. Then consider what level and
type of technicality in the writing will be appropriate for them – and what won’t be. Those
acronyms that roll off your tongue because you use them every day – are they well known
elsewhere? Unless you’re sure your readers will know all the technical terms you plan to use,
it’s a good idea to include a glossary or a list of abbreviations, or both, at the start of a text.
Another strategy is to explain those items in parentheses or footnotes when they first appear.
But if you find yourself doing this a lot, you should probably just add a glossary instead.

3. Poor punctuation
All writers have a passing knowledge of the main set of punctuation marks. Very few,
however, outside of professional authors and editors, have a thorough grasp of how each one
works. The use of full stops and question marks is painless enough, but beyond that there is
widespread difficulty with getting the details right. When exactly are commas required?
Which dashes go where? When should you use hyphens? What’s going on with colons and
semicolons?

How to fix it:

Find a good, modern guide to punctuation and read it carefully until you have a firm grasp of
each mark’s use and misuse. Pay particular attention to any area you have trouble with. If
certain mistakes or difficulties crop up repeatedly in your company’s documents, address
them in your style guide (see next item below).

4. Inconsistency
Technical writing should convey coherent ideas and trains of thought. Unfortunately, this
doesn’t always happen. And that’s especially true when a document is written over a period
of time, created by multiple authors, or updated piecemeal without due regard for overall
consistency and readability. These circumstances are common and can result in choppiness in
the document’s style, layout, tone, point of view, and so on. For example, the text may
address readers as ‘you’ in one paragraph and as ‘designers’ in the next. The tone may switch
abruptly from warm and chatty to scientific. This can be disconcerting, if not downright
confusing.

How to fix it:

If you’re making changes to an existing document, get a sense of the surrounding context –
including things like tone and tense. Try to align your changes with these, so that new
material is incorporated seamlessly (or, if necessary, signposted appropriately). Jumps in tone
or tense can be overlooked even more easily than typos and grammatical errors. The sense is
clear to the writer (or writers), so they don’t notice things that will jar for the reader. These
jumps must therefore be looked for specifically.

Create a company style guide and make sure all your writers have easy access to it and are
encouraged to consult it. This will do wonders for the consistency of your documents, both
internal and external. Ensure that the guide not only includes vocabulary items but also
addresses things like readership, typography, company aims, and brand voice and identity. A
style guide is a living document, so put a system in place for proposing and incorporating
additions and revisions to it.

5. Too much abstraction

People writing in a formal or semi-formal context often go overboard in an effort to make
their prose sound proper and elevated. Their writing, as a result, can end up very abstract and
noun-heavy. ‘The achievement of good performance’ may sound fancy, but it’s a mouthful
compared to ‘performing well’, and it’s really no more impressive than the plain-language
option. It’s also less clear. Abstractions like this are unnecessary and, as they accumulate,
make your prose turgid, verbose, and tiring to read. They can also make it ambiguous: if you
describe a system as having ‘enhanced functionality’, do you mean it has more functions or
that it works better?

How to fix it:

Try to replace abstract, noun-heavy phrases with strong, straightforward verbs. This will
make your points more concise and intelligible. ‘The carrying out of tests’ can become
‘carrying out tests’, or, better still, ‘testing’ or ‘tests’. Watch out for phrases like took place,
which often point to gratuitous nouning and buried verbs: ‘Analysis of the figures took place’
really just means ‘The figures were analysed.’ A related issue is redundancy: ‘blue in colour’
means blue, ‘robust in nature’ means ‘robust’, and so on.

6. Unclear antecedents
An antecedent is a word, phrase, or clause referred to by another word, which is usually a
pronoun like it, they, or who. For example, in ‘Observe the results and add these to a
worksheet’, results is the antecedent of these. Ambiguity can occur when there is more than
one possible antecedent. Take the following: ‘Trainees should mark their schedules in the
notebooks provided, then in the group calendars. The manager is responsible for them.’
Whoever wrote this knew what the manager was responsible for, but readers may reasonably
wonder if them referred to the trainees, the schedules, the notebooks, or the calendars.
How to fix it:

This is a common blind spot for writers, and it shows why we are our own worst editors.
When we review the text, we see only what we meant – we miss the potential for uncertainty.
Have someone else look over the text, if possible, because a fresh pair of eyes will be more
likely to notice problems like this. It’s better to choose someone who is less familiar with
what is being described, since they are less liable to fall into the same trap of overfamiliarity.

7. Dense presentation
Technical writing can be very … technical. Unavoidably so. Applying plain language as
much as possible will help, though you still probably won’t win awards for literature. But
even allowing for its stylistic limitations, technical writing can be made much worse through
poor presentation. Long, unbroken chunks of text, for example, are visually off-putting and
hard to follow. They can make a reader’s brain shut down out of sheer effort and frustration.
The prevalence of jargon and complex concepts add further cognitive loads, and it all adds
up.

How to fix it:

There are several ways to tackle the issue of dense presentation. Short words, sentences, and
paragraphs are generally preferable, though they’re no guarantee of lucidity – it’s more
important to use the most appropriate words in the best possible manner. Some passages can
be broken up with bullet points, which makes them far easier to digest. Bullets also allow you
to simplify the grammar, since they don’t need to be full sentences.

Parallelism can lend grace, polish, and clarity, and is a grammatical device worth attention
and practice if you want to improve your writing. It can take various forms, but essentially it
means using matching grammatical structures in words, phrases or clauses that should work
in parallel.

For example, consider the sentence: For breakfast we like eggs and to grill bacon. Here, eggs
is a noun but to grill is a verb. Better to write: For breakfast we like eggs and bacon, or: For
breakfast we like to fry eggs and grill bacon.

It’s natural to struggle with technical writing, especially if you only do it from time to time.
Producing something that reads effortlessly is a challenge. But thinking about and applying
these seven straightforward tips will benefit your writing experience.

Even more importantly, it will make everything a whole lot clearer – and life a lot easier – for
your readers.

Interested in improving your technical-writing skills? We can train you (or your team) in
that.

Image credit: ALPA PROD / Shutterstock

aceseditors.org

The most common mistakes in technical

and scientific writing — and their plain
language solutions
Romina Sparano
7–8 minutes

July 23, 2020 • By • Resources

We all make mistakes when we write. It is part of the process. And, unlike speech, which is
extemporaneous, ongoing and loosely structured, writing requires revision before you share
your text as a product. Even texting, sometimes called “finger speech” for its fleeting nature,
undergoes editing! (You may not think of it as editing, but, tell me, don’t you find yourself
retyping or, at the very least, shouting at the autocorrect quite often?)

In technical writing, mistakes often go unchecked because specialists would sooner hide
behind the jargon than admit their writing needs work. In their defense, it is true that
technical language is full of terms that have been carefully crafted to reflect granular layers of
meaning, and that there is no real shorthand way to explain them — often only an extended
explanation will begin to express the nuances hidden in a technical term. But, technical
writing is not just about technical terms and therein lies the challenge: No matter how
technical your subject matter, you can always strive to produce an elegant text for your
peers.

That’s where plain language techniques can help. Plain language is the use of wording,
structure and design to help your readers — whoever they may be and whichever level of
expertise they may have — find, understand and use the information you present. It is not just
for lay texts. The plain language movement is a call for cogent writing in technical arenas as
well.

It is true that plain language initiatives in the last few decades have gained traction as part of
a movement to give ordinary citizens access to government information and services, and
adapting text to a lay audience spread from government to private contexts. Think about all of
the medical information about COVID-19 published in The Lancet, The New England
Journal of Medicine, and the National Center for Biotechnology Information that was picked
up and digested for the public by a whole range of publications, from The New York Times
to your local paper. But adapting technical texts to lay readers is not all that plain language is
about.

Adapting texts to technical or non-technical readers is about adequacy — that is, making the
text suitable to the situation and interlocutors at hand. Adequacy strategies include managing
terminology, style and register, using media support for your content, and, of course,
adjusting the level of detail of the information you share. Thus, there is lay adequacy and
technical adequacy as well, and variants within lay and technical audiences that require
special adaptations, such as writing about medicine for youth or the elderly, or about an
innovation for peers or regulators. Plain language is also, and I’d say primarily, about
textuality. Textuality involves using grammar, cohesion and coherence to make text more
than a collection of random sentences and communicate information clearly — in any register
or style.

So, when I edit technical text — whether for lay or expert readers — I always start with
textuality. Without a clear message, you are hard pressed to edit efficiently for anything else.
Here are five tips to help you fix the most common mistakes that make technical texts harder
to read and trickier to understand.

1) Subject-Verb Agreement: Adding information before the verb, such as references in

parenthesis or qualifiers about the subject (as in this very sentence), makes you forget what
you were writing about in the first place. To check for agreement, drop the stuff in the middle
and pair up the bare subject and the verb. Here the agreement is singular: “adding makes,”
rather than “adding make,” adding being a nominalized gerund, that is, an “ing" that
functions as a less formal nominalization.

2) Comma After the Subject: Commas NEVER separate a subject from its verb. The
confusion comes because the subject may sometimes include qualifying or commentary
information between commas. And it is precisely because of the qualifying information that
the comma appears before the verb. The subject, in other words, is at the same logical level as
the verb. Note that the last sentence is an example of such an occasion.

3) References and Referents: Be extra vigilant about pronouns and phrases that refer
backward or forward (technically the two types of endophoras: anaphors and cataphors).
Those referring phrases may not actually pick up the right referent, as in this passage: “Guilt
and bitterness are destructive to you and your children. You must get rid of them.” Here's a
more subtle example. "Few are the teachers who at the age of five can teach children how to
read." Though you can learn tons from five-year olds, I bet you never had a five-year old
teacher in school.

4) Parallel Structures: If you list elements in any way, even if only two, make sure they are
structurally equivalent. For instance, if you talk about activities using “-ing” forms
("walking," "biking," "swimming"), don’t squeeze in a “to” form or a noun ("to jog" or "a
hike"). The same goes for explanations. Compare the first sentence of the first tip with this
(incorrect) version: “*Adding information before the verb, such as references in parenthesis
or when you add qualifiers about the subject, makes you forget what you were writing about
in the first place.” In the correct version at the beginning, “references” and “qualifiers” are
both nouns. In the incorrect version here, the noun “references” is mixed up with a clause
“when you add…”

5) Extra-long Sentences: When expressing complex ideas, consider using pronouns,

nominalization or summarizing words (like “this,” “such + noun,” etc.) to pick up previous
information in a new sentence. These strategies provide a welcome pause, allowing the reader
to process the first chunk of information before plunging into the next.

In case you are wondering, yes, these strategies apply to lay texts too. You may just need to
layer an adequacy strategy on top of your textuality strategy. Let’s say your technical version
had a long sentence that you split into two using the nominalization strategy I mentioned
earlier. Now all you have to do is adapt the technical terms in the two new cohesive and
coherent sentences. For instance, if your first sentence includes the verb “resect” and your
second sentence picks up the information with the nominalization “resection,” you can adapt
those sentences using “take out” and “taking out.”
So, after your first draft, check for these five issues. Your readers will find your final version
not only more readable, but more enjoyable. If you are curious about other common mistakes,
contact me.

Header photo by Aaron Burden on Unsplash.