Technology writing - a guide for beginners

Good technology writing doesn't come easy. Not at first

Most people can write simple, straightforward text even if they’ve little formal writing experience.

That is the best place to start.

Next you need to learn to put your readers first. Understand what they need to know and the barriers they might face getting to the information.

After that, good technology writing is about understanding your subject matter and clear thinking — then turning your thoughts into words.

If you can do this in a logical way, the shape of your story will lead the reader through the key points.

Step one: Start simple

Start by sticking to basic words and simple sentence structures. Don’t worry if this feels like plodding. You can experiment with language when you feel more confident.

Inexperienced technology writers often have one of three faults:

• A pompous and overbearing style. Avoid this by being friendly, although not chatty. And use active language, it is easier to understand and unambiguous.
• Too technical. In other words the writer does not explain the technical aspects clearly enough to non-experts. Fix the problem by keeping jargon to a minimum and explaining tricky ideas in simple terms. You can't assume your readers know all the basics, so make as much of this as clear as possible. Don’t worry if this makes your writing longer.¹
• Trying to be cute. There’s nothing wrong with making jokes or using everyday speech, but beginning writers can take this too far, to the point where it is hard to understand their meaning. Think of how jokes often don't work in emails or text messages.

Hitting the right note

Pitching your copy at the right level is the hardest part of technology writing.

Experienced technology writers know no one ever succeeds by overestimating the reader’s intelligence. They also know no one succeeds by underestimating readers.

Remember people who are expert in one area of technology, may not understand other areas. And a technically literate readership does not give one a licence for sloppy explanations of complex technical matters.

If you find this difficult, imagine you are writing for an intelligent colleague working in another area of your organisation.

• Picture that person reading your words.
• What questions would they ask if you were in the room with them? Make sure your text answers these questions.
• Have you written something they would find patronising? Hit the delete button and make that point again.

Lastly, if you can, always get someone to proofread your copy.

Ask them to point out what doesn’t make sense and to see if you’ve made any obvious errors. Don’t take offence if they find things that need changing. Your pride will be more wounded if the rest of the world saw your mistakes.

Update: I’m indebted to Thomas Beagle for reminding me about bullet points. Like the man says, use them where possible to break up block of text and make your writing easier to navigate.

1. Never worry if geeks tell you your technical writing is too simplistic. They are not the target reader and anyway they probably think they know everything about the subject already. ↩︎