No One Is Going to Pay You to Be Their Spell Check
I often have a hard time explaining what I do to people, and I really shouldn’t, because I explain things for a living. But there’s a lot more to it than people generally think.
Normally conversations about what I do tend to go something like this:
Person I Just Met: “What do you do?”
Me: “Oh I’m a technical writer.”
Mildly Interested Person: “What’s that? Like you write manuals and instructions and stuff?”
*Whitesnake’s “Here I Go Again” begins playing softly in the background*
Me: “Kind of, yeah. Only I don’t do a whole lot of writing really, it’s more rewriting and editing the stuff developers write and pointing out things that don’t make sense to me, so it gets dumbed down and actually makes sense for the consumer.”
Losing Interest Person: “So you’re an editor then?”
Me: “Effectively.”
Not At All Interested Person: “But they don’t call you that.”
Me: “Nope.”
Completely Vanished Person:
I find that no one wants to hear about the details of technical writing when it comes up in casual conversation. They’re more likely asking out of politeness rather than interest. Sort of like when you ask someone how they are, the expected response is something like, “Good, thanks. How are you?” And not, “I’m glad you asked because man do I have some stuff to get off my chest. I am not okay. I’ve been dealing with quite a few existential crises these days, let me enumerate them for you in a long-winded one-sided conversation you aren’t allowed to escape from because you were just being polite and now ya stuck sucka.” And then they lean in, like, uncomfortably close, and whisper at you, “How much do you know about multi-level marketing schemes?”
Anyway, now my canned answer when people ask me about technical writing is, “I write manuals and instructions and stuff,” and I leave it at that. Ain’t no one got time for a lesson on content management using a docs-as-code strategy when you’re at Andrea’s cat’s third birthday party and the cocktail weenies hit the table. I have some friends that have really legitimately complicated jobs, and their usual canned answer when they’re asked what they do is, “I’m in IT,” because that’s just easier than explaining Layer 3 Networking or how DNS works to a layperson.
But that’s actually part of my job — explaining the really complicated things. Or re-splaining it, rather.
Tha Heck Do Tech Writers Do Then?
The meat of technical writing work usually involves taking things that other people have written, and editing it for consistency and clarity so it makes sense to the audience. In my little corner of the technical writing world, when I’m writing for customer consumption, this usually means creating or updating software product documentation, API documentation, user guides, or step-by-step how-to’s. Or more broadly, “Hey customer! Here’s how we put this stuff together and here’s what you can do with it!”
There’s a practice in technical writing called interviewing the subject matter expert where you ask SMEs (developers in my case) a lot of questions to get a deeper understanding of what’s being talked about. Sometimes if the person I’m talking to really hates writing or has no time to do it, I even take it a step further and physically trap them in a room with a whiteboard, record our conversation, take pictures of the whiteboard, type up a transcript, draw out whatever illustrations, and then turn that into actual documentation. That is probably the only part of my job that I think can actually be considered writing, because I’m creating content where there once was none. The rest of it — to vastly oversimplify it — is just editing, water cooler chit chats, a little bit of command line kung fu, Googling things, a fair bit of lightly harassing people to write stuff down, and being mad at build errors.
Quality Check
I’ve been thinking a lot about what qualities good technical writers should have. I’m not saying that I possess all of these qualities, but I think that there are certain baseline things you have to strive for when you’re a technical writer, and below is the list of things I’ve come up with— because no one’s going to pay you to be their spell check. That just doesn’t add value when it comes out of the box with a license for Microsoft Word, or even the free Grammarly web browser plug-in. What does add value, outside of just doing a lot of work, are the soft skills that you pick up and refine over years of being a person who works for a living — like relationship-building and collaboration and maybe a pleasant phone voice.
So here they are — a completely arbitrary made-up list of qualities I think are important for technical writers. Do with it what you will.
#1 — Play Nice With Others
As a technical writer, you need to know who you’re talking to when you’re pulling information out of people. When you absorb information from your SMEs, however you’re doing it, you need to have some understanding of who that person is and how they operate.
I don’t think anything has served me better, not just in work, but also in life, than my being the type of person that actually likes to build and maintain relationships with people. If Brad hates Mondays, but I need to get some info out of him for a product guide, I know not to schedule a meeting on him first thing Monday morning. And also I might send him 87 grumpy cat GIFs on Slack to show him I understand what he’s going through and that I too, hate Mondays, and that I too, am still at work anyway, but in like a, “Hey bud, I get it,” totally cool and chill way. No one likes a pest, and I’ve found that shared hatred of something bonds people like nothing else. It tends to be easier to work with people who want to work with you. If you can find a way to show your personality and be your charming self, people will respond to that more than like a dead-eyed shark stare and an, “I need this from you by next Wednesday,” rank and file type of request. Just be normies, don’t be alarming and scary… and maybe learn how to smize.
I have a very Type B personality, and I’m A-Okay with that. I know from the ~S T A G G E R I N G~ amount of personality tests I’ve had to take during my time in the corporate world that I’m highly flexible, or adaptable, or a third synonym for the same thing. I love to come up with ideas and also potential solutions to those ideas. I also like to be able to see the big picture and figure out how things work together from end-to-end. I can get passionate and fired up about stuff, but I’ve also dealt with enough Security and Compliance teams over the years to know that things are unlikely to work out as I originally envisaged. But no matter how you are as a person, you’re never going to get a 100% likability rating at any place of employment. Navigating office politics and strange work situations can be tricky. There are Negative Nellys everywhere you go, and those people really do suck to work with, but more often than not, people are nice, and will help you if you ask for help.
Have I had to work with highly uptight angry folks who do NOT want me touching the stuff they write because they believe it’s already perfect? Yes.
Does that change the way I operate? Of course it does. But not in the ways that matter.
I have a few chameleon-like qualities, so when dealing with people at work that I tend to call “only-children,” or “mean girls,” I become my most professional self. I am polite and to-the-point, but I don’t use kid gloves or walk on eggshells around pushy people. I try to be direct but not rude, and I do what I was hired to do, interacting with them only when work calls for it. You’re never going to be BFF with some people, and as much as that might have bothered me in my 20’s, at this point in my career and life I have enough other stressors to bump someone not liking me down to the very bottom of the list of things I care about.
At the end of the day, this is a job where you have to be able to talk to people, ask them questions, and collaborate with them on writing projects. Some people are more delightful to work with than others, and no two personalities are the same, but being able to adapt to different people’s work styles and knowing that some people will require a different version of you will definitely help you succeed as a technical writer.
#2 — Write and Think with Empathy
The very first question I ask when I have a new project is always “who is the audience,” whether I’m asking it of myself or someone else. All writing, technical or otherwise should start with the audience in mind. You have to be able to put yourself in the shoes of someone who is consuming your documentation, and write in a way that is going to get them the information they are looking for in the most efficient way possible.
I often start with the notion that no one pleasure reads technical documentation. I’m not precious about the stuff I write. Customers are usually looking at it because they’re experiencing an issue and they want to know how to troubleshoot it, or they’re a new employee and their boss probably told them to brush up on their product knowledge.
As a technical writer, you’re essentially a filter that knowledge passes through, so it’s important to know your audience, which is usually a group of people you haven’t met and are unlikely to actually ever meet. So it requires a bit of imagination, but you have to know who you’re writing for because you’re taking information from an SME and you’re giving it to your audience. So you have to think about end user behavior. Are they going to read word-for-word your brilliantly-crafted 1,000 page document? Think about your own behavior. Would you? Probably not. No. It’s very likely they’ll skip to a certain section and they are going to CTRL+F to find the information they’re looking for. They’re BUSY.
If you’re not writing (or editing) with the audience in mind, ya dun’ messed up already. Whether you’re presenting a couple of PowerPoint slides in a meeting, or you’re cranking out a large manual, it is of the utmost importance to ask yourself what level of understanding your readers have and why they may be looking at that information in the first place.
Look at it this way… I’m sure you’ve been frustrated by IKEA furniture instructions, as have we all, so don’t do that to your audience, m’kay? Don’t cause them physical pain with your words. Save that for the middle school playground. Write for your audience, not in spite of them.
# 3 — Learn How Things Work
It sounds (shouty caps) BRAGGY to say you have to have a certain level of intelligence to do this kind of work, but you do have to have the ability to grasp and understand complex ideas or topics or systems or applications or whatevers well enough to explain how they work to someone who may have no idea how they work. I often tell people my goal is to become an SME through osmosis. Given enough contact with whatever it is I’m writing about, I will retain information about that thing. It’s bound to happen. Often I don’t even know it’s happening until I’m in a meeting and someone asks a question, and because I’ve written the docs and played with the demos in order to write the docs I’m like, “Oh yeah you just go here and here to do that and then push that button and you’re golden.” With deeper understanding of whatever you’re writing about, which is usually gained over time, you can start to ask better questions, spot issues with the documentation, and even sometimes divine what the SME was actually trying to say when they horribly mangled some words together on a first draft pass.
#4 — Stay Humble
One of the most important lessons I’ve learned in my career is that it is okay to not know something, and ask someone to explain it to you. I had a friend at work once tell me, “I always start from a place of ignorance,” and that’s something I’ve taken with me from place to place, because he was a much beloved figure and it happens to be a maxim that works for my profession. It’s impossible to know everything. I’ve noticed that a lot of people in the workplace have this psychological urge to come off as strong and smart, probably because they want to impress their boss and keep their job. But sometimes this manifests itself as that person that always has to say something in a meeting just to seem important. Don’t be that person.
It is okay to not know everything — to not have all the answers — as long as you’re teachable and willing to learn. You have to be willing as a technical writer to ask questions about things you don’t understand, because the alternative is passing off the confusion to your readers.
#5 — YOU HAVE TO BE ABLE TO THINK CRITICALLY ABOUT STUFF
Typically software developers are so deeply entrenched in their technical know-how that they forget to start from the beginning, where someone who didn’t develop this piece of software and maybe doesn’t have that level of technical expertise might need to start. (So, like, pretty much everyone who will be consuming the information.)
“If you wish to make an apple pie from scratch, you must first invent the universe.” — Carl Sagan
Context is super important, and so is not assuming your readers’ level of understanding. Assuming the knowledge-level of the audience is something everyone is guilty of doing from time to time I think, but when you’re dealing with really complex systems and applications you have to figure out where the base level of knowledge should be and start explaining from there. Figuring out how to pull the right information out of developers can be challenging, but sometimes talking to them is a lot like putting glasses on a myopic person. When they can finally see what they missed they don’t usually go back to being blind.
It is okay to point out flaws if you’re a technical writer. In fact, people depend on it. To me, there’s nothing worse than hard-to-decipher instructions that don’t make sense. If you as a technical writer are having trouble figuring out how the thing you’re writing about is supposed to work, just imagine what the user will go through. It is okay to kick it back to an engineer sometimes and say, “I don’t understand this, can you please help clarify?” Nine times out of ten they’ll clarify it, and if they don’t, you’re a writer — just annoy them with words until they do.
I have known tech writers that are doer’s — as in they just pound out words on a page all day, they follow the style guide, they generally don’t have that great of a grasp on the subject matter and if the content is wrong they would never know. They’ll get work done, but they won’t catch errors. It’s quantity over quality — the difference between good and great. And you could argue it ain’t even that good.
#6 — Harness the Honey Badger
You have to be tenacious. As a technical writer, your first priority (documenting how things work) is (and I cannot shout this loud enough) EVERYONE ELSE’S LAST PRIORITY. Just accept that, and know that they have a job to do, and you have a job to do, and it weirdly falls on you to square the two. There is no place for timidity in technical writing. I have known timid technical writers, and they don’t get anything done. I have known aggressively naggy technical writers as well, and people hide from them. In between Timid Tina and Nagatha Christie is a perfect middle that you should probably figure out — and then you should call me and tell me how I can perfect it. Unfortunately this job requires you to lightly badger people into giving you their time and information. There’s an art to it that I have yet to master, but this is why I listed relationship-building first. I’ve found that it’s easier to pull information out of people, even when they have a million other things going on, if they actually want to work with you.
#7 — Be the Perfectionist Your Mom Knows You Aren’t
Technical writers do a fair amount of quality control. We’re usually really good at spelling and grammar, even if our texts occasionally contain a “duck” or two — that’s autocorrect’s fault, not ours. And you do have to have an eye for detail, and the capacity to put up with tedium, because MY GOD, reviewing documents for grammar, spelling, style, and formatting is sometimes just about the most boring thing in the world and your eyes might feel like they’re melting. I once stared at a document so long I fully believe I saw through it and into The Matrix. But such is the burden of the technical writer.
If you are in any way slightly compulsive about things being “matchy-matchy” — this might be the career for you. I have a compulsive need to make the things I write as perfect as they can possibly be. I’m a perpetual editor. I guarantee you that by the time you have read this far, something else on this page — probably some innocuous little comma splice — will have changed. (Yes, those em-dashes used to be commas.) It’s a problem. But it’s why I do what I do.
There are a lot of qualities that make a good technical writer — and being spell check is definitely one of them, but it’s not the only quality a technical writer should possess.
Jen Brown currently does technical writing for Redwood Software, and she’s been picking apart what other people say for her entire life. Jen loves quad roller skating, dogs, meme culture, and webcomics. She is also pretty sure that Elon Musk is an alien.
