What Does a Technical Writer Do?

Lemon Poppy Seed Macaroons, Apropos of Nothing. Taken by Erik Amundsen

At first, I was surprised by the question, and I did not have a good, brief answer for it.

I’ve had terrible answers:

• Well, technically, I’m a writer.

• I’m like a massage therapist for organizations. I find pain points and hammer them until they stop hurting.

• I write (list of the types of document I have authored).

The joke didn’t land either time I tried it. The analogy is accurate, but it’s unenlightening, and the list is just an enumeration of content that a Large Language Model AI can mimic. What I have been missing is an answer that helps me continue doing what I do for my keep in a way that explains its value. This is that answer.

As a Technical Writer, I create clarity, dispel confusion, and support each and every member of the organization.

The product I create is in the form of words; documentation, job aids, help text, all the forms of content I used to list to describe my function. That said, the content is not the majority of what I produce. The process is also the product, and it encompasses the greatest part of what I, as a technical writer, do.

I find out what everyone does. 

The bulk of my workload is listening to Subject Matter Experts (SMEs), recording their words, steps, and clicks, observing their processes, and asking questions. This requires:

• Time. Time to schedule meetings with SMEs, time to record their processes or analyses, time to ask questions, time to draft workflows and outlines, and time to walk through those with SMEs to make sure I and they did not miss anything.

• Patience. Patience to walk through the subject deliberately, asking sometimes ignorant questions and focusing on minute details of the subject. SMEs are human, and when humans get accustomed to a subject or process, intuition and muscle memory overtake defined process. I must transform instinct back into those definitions, a process that not only relies on my patience, but also the patience of the experts.

• Humility. I am not the expert. I may have relevant knowledge and experience, but I am not the expert. The expert is the expert, and their expertise commands my respect. When I can show them that respect, it encourages experts to share their insight as well as their code and clicks.

• Rapport. I am an imposition. Worse, I can be perceived as a threat. It can be hard to see close observation of one’s responsibilities as benign. If the expert feels my mandate is to plunder the secrets they use to remain indispensable and betray those to management, I will fail. If they think I am wasting their time, or just kind of a jerk, I will fail. I have to be honest with my experts, show them respect, take my work seriously, and empathize with their situation to ensure that we work together properly.

• Intuition. I’m not the expert, but the more I can distill from an expert and the faster I can do it, the easier it is on both of us. If I can see a larger picture based on my work and communicate something I see to leadership, it stands to make things easier on everyone. Discovering what background information to research before an interview can speed the process and give more time back to the expert to use their expertise.

• Detective Work. The other side of the coin of intuition. This is research, verification, validation, and the understanding that all humans have bad days, all code has some spaghetti in it, data integrity is aspirational, and every document has a typo somewhere. The old journalism adage serves well here – if your mother tells you she loves you, get sources.

• Recording. I am a Teams apologist; a lot of my time is spent going over recordings of my sessions with SMEs at half speed and making notes. On that subject, a notebook, notes written in longhand, are key. When I must, I take photos with my phone. Some details require repetition to find, and those tend to be some of the most important ones to include. I can find them in this stage or when I turn in a draft lacking them and get feedback. I prefer the former.

I outline and summarize.

I’ve written millions of words no one has ever or will ever read. Full documentation often exists so we can say it exists, and it’s seldom that we break it out.

That said, there is information in any piece of documentation that people will reference, and reference often. I must find that information, distill it down into something easy to understand as a glance and put it on a single piece of paper.

Outlines and summaries allow stakeholders to know what to look for in documentation and where to find it. This is also something I must identify, distill, clarify, and get on a single piece of paper.

Doing this without making the reader damage their eyesight or sanity is my favorite part of the process. Doing this up front lets me communicate my goals and progress with my experts and leadership and frees up my full documentation to be as methodical and thorough as it needs to be to fully communicate its information, without also having to be crackling, page-turning prose.

I write.

Fingers on keyboard, step by step, make the words. Put them in the correct order. Revise the outline and reference materials. Comment areas where I am uncertain and reach out to the experts for clarification. If I have done my job correctly to this point, this is not as onerous as it may seem, though it is always deliberate, methodical, and as thorough as my capacity for executive function allows.

I revise.

In brighter days we had editors who were not the same person as the one who wrote the documentation, but we also had pensions and health insurance. In our fallen world, I get to edit and proofread my own work. In the best case, I can walk away from the documentation for a week and return to it with fresh eyes. This is rarely the case; the more common scenario is that I need to edit and proof as I go.

For proofreading, there is no better method than to print the document on paper, start at the end, and work backward, line by line, with a ruler and highlight marker. Spelling and grammar checkers do not catch everything.

Revision often requires collecting feedback. This can range from a simple check in a box to a full revisiting of the first step, with interviews, walk-throughs, and scheduling calls around experts and leadership performing their actual tasks.

The main difference in the feedback part of the process is that it requires a lot more humility than the interviews. Those who assign me documentation may not know exactly what they want to see until they don’t see it. When this happens, I need to pivot. Stakeholders may have preferences in language and format that they were unaware of before they see something that offends those preferences.

When challenged, I need to be able to explain and defend my choices and preferences or change them to match expectations, usually both.

This is a key to aspect my work. LLMs can generate serviceable blocks of text, but they cannot explain why, given the choice between two passages that are equally correct on a technical level, they chose one and not the other. They cannot disregard the things they have learned if the things they learn create boring language.

Transparency is always the goal in documentation and opportunities to inject poetry into it are rare. Those opportunities, taken correctly, are the difference between documentation that people reference and use and documentation that checks the does-this-thing-exist box.

I publish.

Documentation is worthless if no one knows how to access it. Not every organization wants to pay for a Content Management System (CMS), or believes they already have – it’s me. Hi.

So where does the documentation go? Do we place it in GitHub, Confluence, or Jira, as a wiki on our Teams or a nested file structure buried in the darkest of our SharePoint thickets? With whom do we share this documentation, and how do we let them know it exists and how to find it?

I am using the opportunity presented by my current circumstances to learn some web design and get more familiar with the documentation management capabilities of enterprise platforms. There are a lot of different tools that can manage documentation that are not dedicated CMSs. Someone has to choose one of those tools and use it to its utmost.

My responsibilities to a piece of documentation do not end when the document is approved and published. I need to determine when it is time for a freshness check of documentation, hunt for gaps in coverage, check analytics and manage search tags appropriately.

I fill in.

I learn as I document. If I document everything, I have learned a little bit about everything, and more than that, I know where and how to look up things I do not know. There’s a lot of power in institutional knowledge. I can support business analysts by telling them what I see in our documentation and what people tend to search for when looking things up. I can support leadership by being a scribe or putting together presentations. In a breakdown of communication, I can help stakeholders understand each other’s perceptions and priorities.

I care.

The greatest insight I have gained as an author, the one I would most like to share with the world is this: literally no subject on earth is boring. There is always something worthy of interest in every process, every application, every tool. When I can share that, I win. We win.

Barring that, I can focus in on gaps that cause pain and ease that pain.  All I need is some information. Just the basic fact; can you show me where it hurts?