As a freelance technical writer, my job is to turn complex subject matter into simple, accessible content.

Most copywriters produce beautiful, creative prose that helps sell a product or service. They dream up snappy headlines and killer copy, all the while pushing as many emotional buttons as they can.

They stride into battle on behalf of their clients, convincing readers that their boots are the blingiest, that their chairs are the comfiest, and that their yoghurt is the yummiest. Fashionable people suit up, take a seat, have a nosh, and we all know what’s what.

This is the world a lot of us know. But it’s not the world of the technical writer.

‘Sales agnostic’ writing

By and large, technical writers operate in the post-sales world. And in many cases, no real sale has been made, meaning that we can usually think of the subject area as being sales agnostic.

So, we’re not really talking about selling – at least, not in any overt way. No, the primary aim is to help the reader by providing information that’s clear and easy to digest.

In sales agnostic land, we don’t necessarily want the conversation to go on for too long. Our writing ought to help clients reduce their need to provide end-user support by phone, web, or post. And that saves them a lot of cash, which is reason enough to put some thought and effort into this sort of documentation.

In most forms of writing, it’s best to write in a simple and unambiguous fashion. This is especially important when it comes to technical documentation. In some circumstances, ambiguities could result in harm to the reader – you wouldn’t want to be in any doubt when reading about how to rewire a faulty plug, for example. It’s understandable, then, that technical writing briefs rarely allow room for the client’s personality to show through.

What kinds of document are the domain of the technical writer?

Technical writing applies to any document made up of structured information and that isn’t directly trying to sell to the reader.

Examples include user manuals, health and safety documents, policies and procedures, HR documents, company reports, and tax and compliance information.

The importance of clarity

Technical writing projects often need to serve multiple locales, so it can be important to write in a way that makes it easy to translate the content into other languages. This means writing in clear, unambiguous terms.

But even when it comes to writing material that won’t be translated, we have to remember that the audience may contain non-native speakers of English, so it’s important to cut out idiomatic language – the expressions whose meanings are not derived from the words themselves. For example, a technical writer would write ‘feeling unwell’ rather than ‘feeling under the weather’.

These changes can make the text seem less vibrant and more repetitive, but, for most clients, these are not major concerns when clarity and ease of translation are taken into account.

In fields such as aviation, where clarity can mean the difference between life and death, technical writers are expected to use a controlled language such as ASD-STE100. Such languages use a dictionary of controlled vocabulary, with the words usually permitted to have only one meaning. For example, in ASD-STE100, ‘to fall’ has the definition of ‘to move down by the force of gravity’, not ‘to decrease’.

The process

Here’s the usual sequence of events, based on my experience of working on technical writing jobs in IT:

• Conduct interviews – meet the subject matter experts and gain as much knowledge about the product as possible
• Gather data – collect all the existing material on the subject
• Plan the structure – think of the best way to present the information
• Capture visuals – take screenshots and create videos (depends on scope of brief)
• Preview output – generate a ‘shell’ for each of the intended outputs
• Write text – the important bit!

Technical writing projects are never so simple that everything one needs to know can be picked up straightaway. Lines of communication have to be kept open with subject matter experts, so that the final output is as accurate and clear as possible.

So far as software and hardware documentation projects go, I often find myself becoming an extended member of the development team – someone who asks why things work the way they do, and even how they might work better.

Wearing the right HAT

It’s possible to produce technical documentation using Microsoft Word, but the frequent need to create good quality HTML output usually means a word processor simply isn’t up to the task.

Technical writers favour using a help authoring tool (HAT) such as Adobe RoboHelp or MadCap Flare. Such programs are not cheap but they do have powerful tools for building tables of contents, indexes, glossaries, and other navigational aids.

Crucially, a HAT enables the technical writer to produce several different outputs from a single source. This means a single set of content could be published in many forms: HTML, PDF, Word, and more. Single-sourcing can also be used to produce different content for different users. For example, conditional rules can be applied to provide advanced information to one set of users while everyone else sees only basic information – try doing that in Word!

For these reasons, technical writers almost always use a HAT when working on technical documentation.

Here’s a screenshot of my preferred HAT, MadCap Flare:

How good technical writing can help to sell

Although its purpose isn’t to make a sale, good technical writing content can foster brand loyalty. We want the reader to think: ‘These people really know what they’re talking about’, ‘I didn’t know I could do that’ and even ‘This is so slick that I might just buy another of these devices!’ And when such thoughts percolate in the minds of potential buyers, sales will often follow.

In my experience, the need to produce technical documentation is often an afterthought – an inconvenience. It shouldn’t really be that way, because good technical documentation can enhance the reader’s appreciation of a brand. Perhaps more pertinently, bad documentation could potentially damage reputation and reduce the chances of making repeat sales.

So, in some circumstances at least, there are opportunities to reinforce brand, increase customer loyalty, and perhaps shift a few more units. Note that this doesn’t work across the board: it doesn’t matter how well structured an HMRC self-assessment page is, it’s not going to make you happier to pay your taxes.

Finding out more about being a technical writer

If you think that technical writing is something you might be able to do, I’d suggest you check out the Institute of Scientific and Technical Communicators (ISTC). Based in the UK, this association promotes the professional development of its members, and its online community frequently discusses best practices in the field.