Technical writing, technically speaking
This week, I celebrated my 8-year anniversary of working as a technical writer. It’s a job I enjoy immensely, but it isn’t widely known, so I thought I’d tell you all a bit more about it. Technical writing is a career where I’ve been able to make good use of my knowledge of basic writing techniques, sentence structure and syntax, grammar, and punctuation. I also rely heavily on my written communication skills in order to collaborate with people who have very different skill sets. Unsurprisingly, then, I’ve found a really comfortable niche for myself as a technical writer.
Hang on, though, “technical writing”? What’s that?
To be honest, I didn’t entirely understand technical writing myself before I got into it. My introduction to the concept was my mother reading me results over the phone of a search for “jobs for English majors”; I didn’t initally think much of it, assuming that it involved a level of technological capability that was beyond me. It wasn’t until after my wife got a job in a technical writing role and badgered me (repeatedly) into applying for a job with the same company that I realised that, just like she’d said, I was actually pretty well suited to the work.
The reality of what I do is very different to the vague technologically-minded idea that I started with. At a broad level, technical writing is all about documenting processes and procedures in a way that is clearly stated and easy to follow. That sounds fairly straightforward and unexciting, but it’s a lot more complex than it first appears. This is, in part, because we always think we’re better at explaining things than we prove to be, and bring a lot of assumptions to documenting information that may or may not be accurate (I don’t need to explain how to format a consistent heading style; surely everyone knows how to format styles! Except not everyone does…).
There are also additional levels of complexity in a lot of this sort of work because technical writers are often employed to document processes and procedures used in highly specialised fields that the writers themselves don’t have experience in—the content I work with in my job is intended for medical professionals to use when caring for patients (I and the other writers in my team have no medical experience between us). In these situations, technical writers need to collaborate with actual experts in the fields they’re writing about, such as clinicians in my case, to develop the documentation. The experts bring all their knowledge of what the process or procedure being documented is, what needs to be done, and what someone else in their field following the documentation needs to know. We the technical writers meet that expertise with our own knowledge of how to communicate information effectively, structure sentences in a simple and sensible way, and lay out information appropriately. And in that meeting point we have to ask a lot of questions of each other!
In terms of useful and relevant skills, having a good understanding of the nuts and bolts of phrases, clauses, and sentences is especially important. For a lot of technical writers this can be based in instincts developed from lots of reading in writing, but a solid grounding in theory certainly doesn’t go amiss. We also focus a lot on using plain language—avoiding unnecessary jargon or colloquialism that might not be understood by the target audience and keeping phrasing and structure simple for easy reading.
But it is also very important to remember that technical writing is a team sport! We work quite closely with other people, so having good communication skills is also a vital part of making sure the process or procedure is being documented correctly. It’s also particularly key for us to be good communicators because the experts we collaborate with have a wide range of communication skills themselves, and we may need to bridge a gap with them (which is to be expected; they’re not the ones who are trained and paid to fuss over commas, after all).
The things I’ve learned
My work as a technical writer has taught me a lot, not just about the job but about written communication in general. In order to become a highly skilled technical writer (as I have been well assured I am), I have needed to develop my ability to write clearly and communicate effectively in two different settings: firstly, with regard to the content I am tasked with amending, discussing, and publishing, and secondly in my conversations with the experts I’m collaborating with. Over the last few year I’ve had the pleasure of helping train up new technical writers, and it’s been really rewarding to watch them have the same revelations I did when I was learning the trade.
The following are, in no especial order, a collection of tips and discoveries that I’ve picked up along the way:
Sometimes the best way to fix a sentence (or paragraph, or section, or process of steps) is to take it apart and reassemble it in a different order. This can be complex and confusing, but I also think it’s an awful lot of fun, like a puzzle.
While it is very important to know what questions to ask someone you’re collaborating with, it’s just as important (if not more so) to know how to ask them. Do I want to give them a yes/no decision? Is there an outcome I want to steer them towards? What aspects of the decision do I want to present as being a given? How much of the decision is mine to make and how much is my expert’s? Getting the questions and the approach right is a really key part of effective teamwork.
Microsoft Word really hates formatting bullet lists properly.
Sometimes, the thing someone is asking for isn’t actually what they want or need; they have a particular problem to solve, but they don’t know how best to solve it, and so they give it a shot and ultimately send through a solution I know won’t work. So my job is not to say “no, you can’t do that”, but rather to figure out what the problem they want to solve is so that I can suggest some better options.
Plain language is not a monolith, and changes depending on your audience. The language that is plain and clear for a clinician is going to be beyond my layperson’s understanding of medicine, and the language that is plain and clear for me will oversimplify and dumb down the content too much to be practically useful to the clinician.
Making things BIG and BOLD and BRIGHTLY COLOURED and putting them at the top of the page often isn’t as effective as just putting the information in the right place to begin with.
On a related note, the more exciting elements you have in the content, the less people are going to pay attention to the excitement. If you really want a few key things to stand out, the rest of the content needs to be comparatively toned down—making important text ever BIGGER and BRIGHTER just reduces the overall effect because there isn’t as much contrast to make those things pop.
There is almost never a black-and-white “correct” answer. This is frequently very frustrating. There are, however, often some answers that are better than others. It’s part of my job to know where they sit on the continuum and try to steer in that direction where possible.
When I’m communicating with someone about a piece of work and I have a lot to say, and/or it’s getting complicated, I need to make sure that I’ve very clearly signposted where my message is going, especially where I’m asking the other person to do something or answer a question. (Otherwise, there’s a very real risk that I’ll just end up confusing my collaborator, and that won’t get us anywhere!)
If the sentence is getting awkward and unwieldy, there’s a pretty good chance that it actually needs to be two sentences.
Working with a wide variety of people and content that is unfamiliar to me means that I will very often come across a myriad of weird and wonderful surprises. Sometimes these surprises are not so wonderful (such as the images we use to depict nasty medical conditions), but other times I’ll learn something really cool about the person or topics I’m working with.
People who don’t have a lot of training or experience in wordsmithery can have a lot of awe for those of us capable of such wizardry, and the feeling of delighting somebody by fixing a perplexing sentence they were struggling with is just wonderful. And building up the sort of trust with someone where they can show you the tricky problem that’s doing their head in and just say “please work your magic!” is one of my favourite things about what I do.
You may or may not be a technical writer yourself, or have any interest in a professional writing-focused career, but we all have to communicate to people in written forms sometimes, and hopefully some of these pieces of advice can help you be more effective at it.
Member discussion