Let’s start with the basics.
What Does a Technical Writer Do?
Truth be told, it is difficult to explain.
- I write instruction manuals for advanced computer users - that is what I tell my parents.
- I translate technical English, into customer English - that is what I tell my fellow translators (I started off as a technical translator)
- I describe functions (or features) in a way that customers can use them to their benefit - that is what I tell my fellow Engineers.
Let’s stop for a second and do a quick exercise. Think about how YOU would explain what you do for a living to an 80-year-old person, to your best friend from childhood, and - if you are an Engineer - to a fellow Engineer working in another company.
I am giving you a few minutes… almost there… done?
I think it is safe to assume that your explanation was different for each person. You probably used different words, different metaphors, and even maybe went into detail in some cases more than in others.
Aha! I just used my psychic Technical Writer skills to make my first point. A Technical Writer needs to know the audience they are writing for.
Getting to know your audience in the Kubernetes world is extremely difficult, as Kubernetes users range vastly from Application Developers and IT Executives to highly advanced Kubernetes Operators, Platform Architects, and everywhere in between! This puts us in a tough spot, as our efforts are targeted at many types of audiences. Some of them require more information, while others already know all there is to know and only want to find the right commands.
It’s possible to target a wider audience, but you need to find out which strategies work best for your company, and stick to those strategies for consistency, but, let me save those strategies for another day. Let’s go back to what a Technical Writer does:
A Technical Writer researches, compounds data, analyzes it, abstracts what is important, and uses the minimal amount of information that must be provided in a given context for a given user to be able to use a product or specific function.
I am saying “minimal amount of information,” because nobody in this TikTok-dominated world is reading a wall of text.
But to provide information, we need to gather it first.
What Does a Technical Writer Need to Know? and Where Do We Get That Information?
A Technical Writer needs to understand the function - WHAT and WHERE
What exact steps (commands) need to be run, and where? This information is often provided by the people who build the product, our Engineers.
A Technical Writer needs to understand the workflows - WHEN
When do users need the commands and in what order? The Product and Design departments often paint a picture of what the expected user experience should be. Other times, it is Support that helps provide feedback on the workflows that are easier to follow and more straight-forward. Additionally, Engineers can provide useful information on best practices and limitations.
A Technical Writer needs to understand the problem or gap - WHY
Documentation has to be intentional and straightforward. Why do users need to perform that workflow? The Product and Support departments will tell you why we are developing a specific feature.
A Technical Writer needs to know the audience they are writing for - WHO
In a perfect world, we would have a direct line to our customers to gather feedback, but very few customers are inclined to hop on a call to talk about documentation only, so relying on Support and Product is often the best call.
As you can see, technical writing is like assembling a puzzle. Only the puzzle pieces are scattered in all rooms of your home. Among those pieces, you also find other pieces that do not belong to your puzzle. This means that you not only have to fetch the pieces from all rooms in your home, but you also need to figure out which pieces belong to your puzzle, and which ones belong to a different one.
Disclaimer: I am not saying a Technical Writer must write extensively on each single one of these items. But they need to know these things, so they can make an informed decision on what information to include and what not to include.
Let’s go back to our original question.
What Does a Day in the Life of a Technical Writer Look Like?
Every Technical Writer works differently, and every company has their ways of doing things, but at D2iQ, I can roughly say that:
- We spend around 60% of our time researching, and reading.
- We spend around 20% of time interviewing subject matter experts (SMEs) and department representatives - AKA asking questions like a 5-year-old - sometimes because the full picture is not clear, and sometimes because we want you to think from a different perspective.
- We spend around 10% of time learning about the product - but not too much, or we would not be able to represent the NOT all-knowing customer.
- We spend about 10% of time actually writing.
And we drink lots of coffee, tea, or any other caffeinated drink that will help us focus.
I hope this gives you a glimpse into the life of a Technical Writer.
In this article, I have tried to sum up the essence of our profession from a more general perspective. We can get down to the more nitty-gritty details in another blog post, or cover other tasks like working with a Content Management System (CMS), employing content reuse and maintenance strategies, documentation release work at General Availability periods, etc. We can also get into how, at D2iQ, a writer is integrated into each of the Engineering teams to facilitate collaboration and coverage of the features during the early development phases.
Stay tuned for more perspectives on technical writing!