The Secret Life of Technical Writers

No dinner party is complete without someone inevitably asking, “And what do you do for work?”. As a technical writer, you’ve got to love those questions because most people look a little confused when you say what you do. Then again, I don’t blame friends and family for not really knowing what technical writing is. Before I started my career, I hadn’t even heard of technical writing (or, if I had, it didn’t register).

What does technical writing entail? What does it take to be good at it? Can anyone do it? You can’t really answer these questions in less than three sentences (as much as a trained technical writer such as myself might be itching to do). Instead, let me gingerly step out of my comfort zone and do it in less than 1000 words, because context matters. Oh, and because a three-sentence blog post wouldn’t exactly make the rounds, would it?

Wordsmithing, or using the right words at the right time

For as long as people have used written language to communicate instructions (and it’s been at least this long), there existed the technical writer. Still, we’ve come a long way since the times of Carthage, and so has this noble profession. But let’s not drop too many historical references just yet. To better understand what we do, picture the technical writer as a swordsman. They’re not that different (sans the danger of maiming).

Much as one wields a sword, so does the other wield language: with precision and skill. In technical writing, though, the duel may be with yourself. Or, more precisely, with your involuntary reactions or habits. You have to know when to parry an unnecessary phrase, riposte with a clear sentence structure, and lunge with just the right words for the final strike. The duel can become especially heated when you consider that you need to be able to adjust your tone and lexicon to the target audience. Striking the right balance between technical jargon and patronising basics is the key to giving your audience what they need. After all, as Tom Wardak elegantly puts in Communicator, “Complex concepts don’t mandate complex explanations. Tangled prose reflects a tangled writer with a loose grip on their subject matter.” He also explains that superfluous words, like adjectives or pronouns, which inject interpretation and uncertainty, need to be done away with because “technical writing has no ego or agenda, it is pure craft” (Wardak, 2020).

Boldly testing the product

We’ve established that a writer’s primary weapon is language. But do you also need to be a technical wiz? Ideally, you’d have the knowledge of an expert but, in reality, you don’t have that kind of time. What you need is curiosity. What you don’t need is fear. You can’t be afraid to play around with switches, toggles, or scary red buttons (in the right environment), and, just as importantly, you can’t shy away from asking questions. Experimenting with the product we’re describing and filling the gaps in our knowledge by asking the right questions is our bread and butter, after all.

What is more, our perspective as we’re learning the ins and outs of a piece of software or hardware can be invaluable. This perspective can be a challenge to a developer, who’s often too engrossed in the nitty-gritty, too familiar with the product, and, consequently, prone to make assumptions about the user experience. But beware: as you grow familiar with the subject matter, you face a similar risk! Even so, the technical writer is often blessed with the opportunity to make life easier for the user, even at the early stages of feature development. Joaquim Baptista seems to share my point of view: “Writers are often the first to look at new features from the point of view of their users, and wonder: Will this feature make sense to the users?  How will users solve their problems with this feature? (…) It is through our unique point of view that we add value to the company, by doing things that others at the company fail to see” (Baptista, 2020). It’s the kind of empathy a machine can’t yet replace. And that’s a comforting thought.

Designing a solid structure

A technical writer doesn’t just test out new features and describe them. There’s one more secret ingredient, one final form they need to assume: that of an information architect. Language is one aspect of making content digestible, but that same content also needs to have a structure that’s easy to navigate through. To that end, technical writers often use information models or templates for various types of content, such as installation manuals, quick start guides, and so on. It is crucial that we’re mindful of the flow of information and make strategic use of elements such as headings, lists, figures, and even space (Last, 2019). Browsing through a haphazard collection of articles or scanning a wall of text to find what you’re looking for is much like finding a needle in a haystack. Speaking of findability, here are some tips on why it’s important and how to improve it!

In the words of Lief Erickson, a successful information architect “helps organise content in a logical and meaningful way, so that it is easy for readers to find and understand. Your readers will recognise the patterns of a page structure as well as the navigation. This can improve the effectiveness of the content and make it more likely that users will take the desired action” (Erickson, 2023). In other words, what use are your neatly written and technically kosher instructions if no one will bother reading them? As Suzan Last aptly puts it, people often read technical documentation because “it’s part of their job. And since ‘time is money,’ the longer it takes to read the document, the higher the ‘cost'” (Last, 2019). That’s why tying it all together within a well-thought-out architecture is what makes a technical writer good. Elementary, my dear reader, and we’ve already stressed why writing well matters.

The secret in a nutshell

Well, time to answer the question we set out with. What do I do at work? I simplify the elaborate, play a bit of Tetris, sometimes see how far things bend, and maybe write a word or two, every so often. Want in? Be linguistically competent, have a curiosity for the technical, a flair for information design, and you, too, can make complexity clear.

References

Wardak T, Tech-comms as Linguistic Tetris, Communicator, Winter 2020, page 30.

Baptista J, On becoming a technical communicator, Communicator, Summer 2020, pages 33-35.

Erickson L, Information architecture, Communicator, Spring 2023, pages 17-18.

Last S, Technical Writing Essentials, University of Victoria, 2019, Chapter 3: Document design.

Naylor D, Empires, wars and revolutions: a brief history of technical writing, www.3di-info.com.

Potts R, Why the skill of writing well matters, www.3di-info.com.