Many writers like to complain about editing. It’s often tongue in cheek – for example, the novelist Ian Rankin likes to tell Twitter about the cruelty of his editors forcing him to fix things when he thought he was finished – but sometimes it’s genuine. The writer has produced a masterpiece and hates being told that it isn’t perfect.

The writer is usually wrong, because almost everybody benefits from having an editor look at their work.

No matter how much effort and expertise you’ve put into your writing, the first version can almost always be improved. There’s a reason newspapers, magazines and book publishers employ editors: they take the writers’ work and make it better.

Editing is particularly important in technical writing because mistakes can have consequences. A mistake in a novel about pirates isn’t the end of the world. A mistake in a bomb disposal procedure manual may well be. Your writing may need to be checked for legal compliance, or to ensure that an absolute beginner can follow it.

No matter what kind of technical writing you’re producing, it’s a very good idea to have somebody else cast a (constructively) critical eye over it. That’s easier than ever before thanks to collaborative tools such as Microsoft Word’s or Google Docs’ collaboration and commenting features. And if there isn’t anybody who can do that, you can become your own editor.

But first…

LET GO OF YOUR EGO

There’s a very good chance that the bits of writing you like best are the first things you need to get rid of. That excellent joke, snippet of a song lyric or Game of Thrones reference would be great in informal writing, but there’s rarely a place for it in technical writing. Think of it like optimising programming code, removing duplicates from a database or compressing files. You’ve created a piece of writing and now you need to maximise its efficiency.

WHAT TO LOOK FOR WHEN YOU’RE EDITING

There are five key things to look for when you’re editing technical writing.

Let’s take each one in turn.

ACCURACY

If a piece of technical writing isn’t accurate, it’s a failure at best and downright dangerous at worst. If you’re telling the reader to cut the blue wire when you mean the red one, to fill the tank with petrol when you mean diesel, or to press Cmd + X when you mean Cmd + V then you’re committing the ultimate sin of technical writing: telling somebody to do the wrong thing.

Accuracy is just as crucial even when you aren’t writing how-tos. If you’re writing about regulations or legislation, there is usually a very specific set of criteria that somebody or their organisation must follow; and if you’re using figures, even a minor error could throw the entire formula or final total horribly out of whack.

And of course, there’s your spelling and grammar. If you’re writing for other languages, it’s a good idea to switch your writing app’s automatic checkers (if it has them) to the language you’re using. For example, switching to US English when you’re writing for American readers will ensure you use ‘center’ instead of ‘centre’ and ‘organize’ instead of ‘organise’ and so on.

Measurements matter

Using measurements in technical writing is rather like using measurements in a recipe: there’s a world of difference – and possibly a world of pain – between 1tsp and 1tbsp of Sadistic Steve’s Frighteningly Fierce Painful Pepper Sauce.

Some measurements are easily confused. For example:

A gigabyte (1GB) is eight times larger than a gigabit (1Gb). This is often confused when describing connection speeds, which are usually expressed in megabits or gigabits: a 1Mbps connection will download 1 megabit per second, but it needs eight seconds to download a megabyte.

In IT, prefixes don’t use the same system as they do in the rest of the world – so while we all understand K to mean 1,000 when we’re talking about kilograms or kilometres, IT uses binary and not decimal numbering. That means in IT, K means 1,024 and not 1,000. A kilobyte is 1,024 bytes, a megabyte is 1,048,576 (1,024 × 1,024) bytes, a gigabyte is 1,073,741,824 (1,024 × 1,024 × 1,024) bytes and so on.

Don’t just ensure that you use the correct units. Make sure the readers know exactly what you mean too.

Compliance

Compliance means following the rules. Those rules aren’t just the rules of effective writing and of the organisation you’re writing for. They may also be rules set down by external bodies. Some industries, such as financial services, the pharmaceutical industry, healthcare and the oil and gas industries, have very strict regulations that they must adhere to and those regulations may apply to the documentation you’re producing or the information you’re giving others.

When helpers aren’t helping

Be very, very wary of computerised helpers such as AutoCorrect and AutoComplete when you’re creating technical writing and keep a sharp eye out for their errors when editing. It’s all too easy for the automated helper to replace something correct that it doesn’t expect with something incorrect it’s happy with.

It’s a similar story with spellcheckers and grammar checkers, which don’t always catch things such as homophones, which are words that sound the same but which are spelled differently. ‘Their’, ‘they’re’ and ‘there’ are homophones. So are write/right, to/two and mail/male. If you’re relying on a computer spelling or grammar checker, it’s a good idea to get a colleague to look over your work too.

Opinions and anecdotes

Technical writing is no place for opinions and anecdotes unless they help to illuminate something that’s otherwise hard to explain. It should be absolutely clear what’s a fact and what isn’t, and if something isn’t a fact it needs to be doing an awful lot of work to justify its inclusion in your text.

SIMPLICITY

Appropriately enough, this one’s simple. You’re looking for anything that makes your writing less friendly to the reader: too-long paragraphs, unnecessary use of long words, the passive voice, jargon and anything else that might make the reader go ‘eh?’

In how-tos, simplicity goes hand in hand with consistency. For example, if you’re going to be telling people to press particular buttons or click particular icons it’s important to keep the same formatting conventions and language every time you tell the reader to do something.

Don’t forget the cliché that a picture paints a thousand words. If you’re writing for print, sometimes no amount of excellent writing will be as effective as a picture with a big red arrow on it. Online, a YouTube video may do a better job than 10 pages of perfect prose.

BREVITY

It’s very easy to write too much – I do it all the time, because I find it’s easier to write too much and then make it more punchy when I edit – and some forms of flab are easy to spot and take out. For example, irrelevant background information should be the first thing to go.

When you’re editing a piece of technical writing, the constant question should be: ‘does this bit help the reader?’ ‘Would this section be just as clear, just as helpful, if I took this bit out?’ If the answer is yes, take it out. You’ll be surprised by how much you can remove: you can typically reduce your total word count by around 20 per cent while making your document more readable and more useful.

EFFECTIVENESS

Technical writing exists to do a specific job. There’s no room for vagueness: your writing is either an effective manual, procedure, tutorial or guidance note, or it isn’t.

One of the best ways to evaluate technical writing is to get somebody else to review it or, if appropriate, test it. Ideally that somebody should be much less knowledgeable about or experienced in the thing you’re writing about than you are, because most of the time that’s the kind of person you’re writing for. If you’re writing about something highly technical, it’s also a good idea to have an expert check it for accuracy.

Let’s say your writing is a how-to for a new software application that nobody in the company (other than you, of course) knows how to use. The test of its effectiveness is clearly whether somebody who isn’t you can get the results they want without getting lost, confused or terrified. And it’s crucial that if they do get lost, confused or terrified that they provide feedback to tell you what the problem is and where they encountered it. You can’t fix problems you don’t know about.

Real-world testing is a particularly good way to spot the kind of assumptions we all make when we know a subject inside out: what’s really obvious to us might not be obvious to somebody else, and feedback enables us to fill in any gaps that might cause confusion.

Think of it like driving a car. So many of the things you do when driving are completely automatic. You don’t need to remember which pedal to press when you want to brake, or what you need to do to change gear, or where the windscreen wipers are. But when you sat in a car for the first time, you didn’t know any of those things. The same applies to someone who’s just joined the department, or who hasn’t encountered a particular system or policy before.

Testing and getting feedback helps you to identify any bits that need more detail.

There are all kinds of ways to get feedback. For small projects or small groups, it might be as simple as having a conversation with the person after they’ve used your document, or watching someone trying to achieve their objective with your document. For big projects and groups, you might use analytics software to track page read times, links clicked and other important information, or you might have a feedback link on online documentation. You might use surveys, or group meetings.

When you’re testing your writing, it’s worth returning to the personas we explored earlier. The feedback method that suits you best might be the least appropriate for your target personas, and there’s a world of difference between assessing documentation in a classroom environment and in a real working environment with all its stresses and strains. The more you tailor things to the people who will be using your content, the more useful the feedback you’ll get.

SHEER TEDIUM

Technical writing is often boring to read. Sometimes that’s unavoidable because you’re writing about something that’s boring. But sometimes it’s because you’ve produced something unnecessarily boring by accident.

One of the best ways to check for boring content is to read your writing aloud. Sentences that looked just fine on paper may have you propping open your eyeballs by the mid-point. Overly long descriptions can have you losing the will to live long before the end of the paragraph.

I’m not suggesting that you should write in the style of an overly caffeinated children’s presenter, and, as explained in previous chapters, humour in particular doesn’t translate or age very well. But if your writing is an alphabet soup of acronyms and you rarely use a sentence when 16 paragraphs will do, there’s a good chance you could make it a lot more reader-friendly. Can it be explained in a more interesting way, or with an even better example? Could the language be simplified?

Mix it up

One way to keep your writing interesting is to vary the length of sentences. On average, a good sentence is around 15 to 25 words long, but if you wrote everything to a 25-word target you’d end up with something that felt really weird and robotic.

The sentences in that last paragraph were 14 words and 32 words respectively. And sometimes shorter is better (that one’s five words).

When you’re writing, take a look at it in full-page view. Is any paragraph a forbidding rectangular block of 87 words with precious little white space and sentences that go on forever, adding lots of words to the original point without actually doing anything constructive, resulting in something that if you were to read out in one breath would have you keeling over because it takes so long to read that you’d run out of oxygen long before you reached the second-last comma, which came before another bunch of words that did absolutely nothing of any use whatsoever?

You get the point, I’m sure.

You can mix things up in other ways too. A well-chosen image or embedded YouTube video can often help illuminate a tricky subject, while good use of typography and formatting, such as breaking long sections into headed sub-sections, can help draw the reader’s eye to the most important bits of information. If you’re writing for an internet or intranet system, you can hyperlink to related or background information instead of including it, or provide fast links to related parts of your own content. Just remember to keep checking links to ensure they’re still current. Nothing dents confidence in an online system more than a 404: Page Not Found error.

KEY TAKEAWAYS