How do you make technical copy easy to read?

March 7, 2014 •
A blackboard showing a lot of technical content

A gentleman from a waste water services provider emailed me, the other day, with this suggestion for a blog topic:

“How about writing about how to take a relatively complex technical concept and making it easy to understand for non-technical people? Thats something I personally struggle with.”

As an ex-technical writer (I worked in the software industry for 9 years, before starting Divine Write in 2002), this is something I’ve thought a lot about. Something I’ve had to master, just to keep my job.

Obviously there’s no simple answer. But there are a few tricks of the trade you can use…

Don’t muck around – Get started immediately

It’s tempting to provide every little detail. Don’t! Include only the information you actually need to include, and nothing more.

Of course, that’s not to say you should remove everything but the facts. Far from it. For example, your back-story may help the reader better understand your content, or it may increase conversion. The point is, make sure every word is justified.

Don’t take knowledge for granted

Many of your readers won’t know much about your subject matter. And everyone will know different bits. So you can’t assume much. And where you do assume knowledge, make sure you’re 100% confident your readers know it, or at least link off to an explanation.

For example, if you’re writing an instruction, document even simplistic steps, and steps you think may be peripheral to your subject matter. Don’t just say, “Click Reset Password in the user’s Account settings.” Say:

1) Log in
2) Go to your dashboard
3) Click Your Account (at the top right of the screen)
4) Select the Users tab
5) Locate the user’s name, and click Reset Password next to it

The system will then send them an email with a temporary, randomly generated, password. Once logged in, they can change their password to something they’ll remember.

Bold the important bits

You can see in the above instruction how helpful this can be.

Talk about the alternatives

One great way to highlight what something is (or what its benefits are) is to talk about what it isn’t. For example:

“It’s not just a new way of logging in, it’s an entirely new way of encrypting data.”

You don’t have to actually say it is something or it’s not something, either. You can say it indirectly, like this:

“Where do you currently keep your files? A filing cabinet in the study? What if there’s a fire or someone breaks in? The family laptop? What if you lose it, it dies or someone hacks it? Other ‘cloud’ solutions? They don’t deliver the same high level of security as our product.”

Make it goal-oriented

Readers understand what they’re trying to do. So if you discuss your technical content in those terms, they’ll not only be more engaged, they’ll also be more likely to understand. They want to understand solutions to their problems. They want to understand how your product or service will make them money. They’re not particularly fussed on understanding isolated technical facts.

For example, don’t just say, “With our product, you can share documents so other parties can digitally sign them.” Say:

“What if you need to share a document? Say you need a signature… You can’t email it, because most digital signatures aren’t legally binding. So that really leaves just two options: A time consuming personal visit or a snail-mail. Neither is very practical given today’s tight deadlines.”

Break it down into chunks

If you’re explaining a really complex concept, break it down into bite-sized pieces. Then explain each piece. This way, the reader can digest your explanation far more easily. Here’s an example from my SEO ebook:

Break technical concepts into chunks

The same applies to instructions. If an instruction is more than about 10 steps long, consider breaking it into two instructions.

Compare complex concepts to things your reader already understands

For example, if you’re talking about security, don’t just say, “Our security uses a unique 16 step process with 23 stages of encryption and decryption.” Say this:

“It’s even more secure than online banking.”

It doesn’t have to be a real-world thing, though. If you know the reader has already mastered a similar concept or performed a similar task, refer to it. This can work as a shortcut to understanding.

Use short sentences and paragraphs

This is good advice for any copy, but particularly so for technical content. Try to convey just one idea per sentence. And that idea need not be (usually should not be) the entire concept you’re trying to explain. For example:

“When you sign up, the system automatically saves a unique digital key to your computer. It’s called your Private Key. Then, whenever you save a file, it’s automatically scrambled – or ‘encrypted’. This creates what’s known as a ‘file encryption key’.

The system then splits the file encryption key into segments, and protects those segments by applying Public Key encryption.The file is then completely secure.

It can only be unlocked with your Private Key. In other words, only on your computer and with your login.”

Give them an immediate opportunity to act

Most people would rather do than read. They’ll scan the page looking for stuff they can actually try, then and there. Importantly, this helps them learn too. So you should try to give your reader things to do.

Obviously if you’re writing an instruction, it’s natural to include practical steps. But you can also do it, even if you’re simply explaining a concept.

For example, you might prompt your reader to sit up straighter in their chair, look at their computer monitor from 3 metres away, or walk outside and look at their car’s engine. These are all practical steps.

It doesn’t have to be something specific though. “See for yourself…” and “Try this now…” are also immediate invitations to act, and far more engaging than, “You can…”.

Use active language

There’s nothing more boring than hearing someone say, “When the Submit button is clicked, a new screen will be invoked.” Don’t do it. Say this instead:

“When you click the Submit button, you’ll see a new screen appear.”

Use conversational, personality-filled language

Your product or service may be technical, but that doesn’t mean you have to write like a robot. Talk like you would, face-to-face. Readers are people too, you know! Some quick rules of thumb:

  • Use contractions (“you’re” not “you are” – See also: Contractions in copywriting – When can I use them?)
  • Tell stories
  • Be open and honest
  • Use emotive language
  • Address the reader directly – use “you”, not “the reader”
  • Use incomplete sentences if you need to

You’ll find lots more info on these tips in the ebook I wrote with Australia’s leading blogger, Darren Rowse (aka Problogger) – The Copywriting Scorecard for Bloggers: Score your post out of 100.

Avoid jargon

Don’t use jargon to explain stuff, unless you have to. And when you do use, explain it. For example, if you’re talking about encryption, say something like this:

“It’s all about encryption. Everything you save in our product is automatically scrambled, so you can’t open and read it without the right ‘key’. Not a physical key, like you’d use in your front door, but it works in much the same way…”

Illustrate it

You know the old saying: A picture paints a thousand words? It’s true. So whenever you can, supplement your writing with pictures. It might be a screenshot with a button highlighted, or a simplified illustration or animation of a functioning engine cylinder.

This won’t just help you reader, either. It will help you too. I’ve generally found things that are hard to write are easy to explain with a picture, and things that are easy to write are hard to explain with a picture.

For example, it’s easy to write that something is “The world’s most secure online storage”, but hard to convey that claim in a graphic. Whereas it’s hard to explain how a private key decrypts an encrypted file, but relatively easy to illustrate it with a picture.

Address possible mistakes

This is particularly important when people are carrying out complex tasks. And if your reader fails a task while following your instructions, they’ll stop reading altogether. Even if it’s not your fault. So try to build error recognition and recovery into your writing. For example, help the reader:

  • Prevent mistakes – Warn them (e.g. “Ensure you do this before doing that”) and highlight things that aren’t typical
  • Detect and identify mistakes – e.g. “If this fails, you may have entered the path incorrectly”
  • Fix mistakes – e.g. “Re-enter the path”

But try not to break up the instruction with notes, cautions, warnings, etc. Put them at end of instruction instead. Most readers won’t encounter problems, and you don’t want to make everyone suffer for the sake of a few.

Provide closure

People like to know they’ve achieved something. It gives them a sense of satisfaction, and will endear your content (and product or service) to them. One commonly advocated way to provide closure is to summarise what the reader’s goal was, what they’ve learned, and how they’ve achieved their goals.

But while this can work very well in long pieces (e.g. presentations, manuals or video tutorials), it doesn’t always work in short pieces. If you feel this approach won’t work for you, don’t worry. Even if you just conclude with something as simple as, “And that’s it!”, you’ve let your reader know they’re done, and that they can tick one more achievement off their list.

Summary

I suppose the most important take-away here is to be creative. Don’t just blurt stuff out; think about human psychology and behaviour, and try to find ways to satisfy what people actually need. Even if that means breaking the rules of grammar and disappointing your high-school English teacher. 😉

Feel free to comment...
comment avatar
camilla peffer wrote on March 8th, 2014

Great post Glen! I work as a copywriter for an IT company (well...for another week at least. Then I'm off to enter the fashion industry!) I've found that highly technical language is incredibly tricky to dumb down. One of the greatest tricks I've learned is to hop on to Whirpool and look at what everyone's pain points are. For example, if I'm writing about Microsoft Exchange, I can hop on the forums and find out that people want email that's reliable. I've also heard that reading Amazon reviews can be helpful too. Just curious, but as a technical writer, how did you manage dealing with legal departments? I find that they have a tendency to want to make my copy sound more "professional". And by "professional" I mean robotic and boring and convoluted, with a billion qualifying statements and unsightly asterisks!

Reply
comment avatar
Glenn Murray wrote on March 10th, 2014

Hi Camilla. Great suggestion (Whirlpool)! I'll keep that one in mind, in future. And Amazon. Re your question about legal departments, I never actually had that problem when I was a technical writer. Had it a few times as a copywriter, though. For instance, when writing about the Toyota Camry, I wrote "extremely fuel efficient" and the legal department told me I wasn't allowed to say that, but I could say "very fuel efficient"... :-\

Reply
Leave a Reply

Your email address will not be published.