How to fix the 7 most common glitches in technical writing

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.

And 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