What is Technical Writing?

What is Technical Writing? How hard can it be to answer that question? There is “technical” and there is “writing”, so we write technical things, or we write things in a technical way, or both. Right? Almost. Defining Technical Writing may require more depth than that. Not only because this profession is complex and multi-faceted, but also because there is a frequent confusion between Technical Writing’s production and Technical Writing’s purpose. If it is any consolation, the same goes with medicine[1]. I’ll do what I can to help you out.

First of all, Technical Writing is a profession. You may be a software developer and perform Technical Writing tasks on the side as support to your coding activities. In this case this may come as a surprise to you: some people do the writing full time. They may use a variety of tools, not just GitHub or Markdown. They may have to interact with a variety of people, not just colleagues and Product Managers. They may even have to describe and explain products that they didn’t develop themselves! Do you want to make it your profession yet?

The cocktail party definition

Let’s start simple. When someone, a friend, family, or anyone not related to my usual professional sphere, asks me what I do, it usually goes like this:

-      I'm a Technical Writer.

-      What's that?

-      I'm the person who writes the user's manual that you get when you buy something.

-      Oh, I never read those.

-      Haha, me neither! that's fine, I'm not offended.

And then I stop talking to that person for the next couple of years.

As simplistic and limited this description may be, “the person who writes the user’s manual”, it is effective as … something very effective.

The Technical Writer is responsible for the creation of this artifact that everyone knows, whatever their profession, education, age, etc. Everyone, at some point, had a user manual or a set of instructions in their hands or on their screen. So just by naming that artifact, we are automatically identified by anyone as the specialist who creates that exceptionally annoying piece of literature which can sometimes turn out to be helpful.

The downside is that in most people’s mind, writing user’s manuals is all we do, and making them only involves collecting and writing down technical details, possibly in a small room in the basement. And we probably all look like John Turturro in his fifties.

We do a bit more than that. For example, we often need to be people’s persons. But it’s ok, the cocktail party line is doing fine in most cases, we should take advantage of it. Believe me, the Usability people don’t have it so easy.

The one-sentence-fits-all definition

One thing about us Technical Writers, we like to be precise. Accurate. Comprehensive even, although I will have to write about that someday. So the cocktail party definition is something we fall back on only under threat of awkward conversation. If we are given a little time and attention, we would rather give a description where everything that we can do could fit. However, there is so much that we do, if we wanted to keep a reasonable level of detail, we would be forced to steal 20 minutes from anyone who wants to know. That would be mean! We have to generalize, take a higher vantage point, and come up with something along these lines:

“Technical Writing is used to inform, instruct or direct a specific audience through maximum clarity and precision with a specific tangible goal in mind.”

I have found this definition in a presentation. There are a bunch of those around.

It is one of those definitions. You think you’re having elven bread and turns out it’s a slice of watermelon. Lots of water and a few seeds. It tastes good though. It may look like I’m criticizing. All right, I am. But each time we try to shoehorn in one Twitter-sized statement every aspect of a complex thing, we end up with an outline that can never show us actually what the thing is about.

In the case of the definition above, we see that Technical Writers provide something to an audience, and it has to have certain characteristics (are “clarity” and “precision” necessary and sufficient to call something “Technical Writing”?), and also a certain goal, in addition to the goal specified at the start of the sentence. It seems a lot and still in the end, we're having a hard time seeing what the Technical Writer is doing.

I don’t want to get too focused on that particular definition, there are many others with some change of words, but sharing the same issues. I think there is a way to find one, though, if we focus on the purpose of our activity and try not to get distracted by the way we think it should be done.

Before we get to the definition I want to suggest, we should examine an information source where the question “What is Technical Writing” gets answered repeatedly, in an infinite number of ways. Maybe by regrouping all those “answers”, we’ll have a better idea of what our profession is.

This source has no shortage of descriptions, characteristics, goals, examples, practical details, requirements, and it is accessible to everyone: Job Offers!

The what-you-signed-up-for definition

Most job offers have at least two sections, sometimes three. Of course some have one, some four or more, and others are completely mixed up, presenting just a small heap of nothing, but that’s just exceptional employers showing their colors. The two main sections are: the tasks you will carry out, and the skills you are expected to possess. The occasional third one is presented at the top of the offer; it is a description of what a Technical Writer is.

Ignore that introductory part. We have seen that Technical Writing is complex, and here is a definition provided by someone who is known for misunderstanding what Technical Writing is. Better not rely on it too much.

The list of skills is closer to what we are looking for. But again, employers are not known for identifying accurately the skills that we need to do our job correctly. Besides, a large part of those skills is tool-oriented; in other terms we are required to have years of experience in whatever tool they are currently using. There are many of those, and they change with time. I think that among about one hundred offers, I have seen “ability to learn new tools” only twice, even though that is what Technical Writers are doing constantly, just like the larger part of the working population those last seventy years (including the people who define the list of skills)[2].

On the other hand, the tasks described in the offer are supposed to be the ones that we will actually carry out during our stay, so they should provide a close enough description of what a Technical Writer is normally paid to do, even though there is a whole set of tasks that are not expressed there. I’ll focus on those here.

During the summer of 2020, I collected two dozen offers coming from American companies, most of them published on LinkedIn. Some of those offers were unusable. The tasks were badly defined, or nonexistent. We are discarding them. I have to mention that quest for a “very particular set of skills acquired over a very long career”: an offer that doesn’t describe anything other than a list of 22 skills (“Skills”, “Required skills”, and “Preferred skills”). We can’t help but wishing them “Good luck!”.

I had to put some order to that big juicy bag of tasks, for your sake. Also, a same task could be expressed with a variety of words, I regrouped those under common labels. Be aware that I collected offers from the software industry. Other products of services may require additional tasks, that are not part of this list.

I have made two categories. The most common tasks are often considered, by our employers, as the core actions a Technical Writer does. The rare tasks are rarely mentioned or requested by an employer. A common task would be found in most offers, whereas a rare task would be found in only one or two offers. However, seasoned Technical Writers could consider that some of those rare tasks are the essence of Technical Writing. This is why I call them rare rather than secondary, or optional, or anything that suggests a difference in importance.

Common tasks

First come all the tasks directly related to the artifacts that we create.

 

Figure 1: Artifact-related common tasks before grouping

So… more variety than just “Write a user guide”. Also you’ll notice that an intermediary is usually present between the action and the medium. For example, instead of “Create tutorials”, we would have “Create instructions for the tutorial”. It is not always necessary to specify it, but at least we see that there are different possible components to the artifacts we create and that most employers feel the need to specify them. Writing a “how-to” is considered different than creating a process. I did both, I can confirm.

Note the presence of special tasks, that you need to be aware of if you want to be a Technical Writer. Things like: “Create Instructions for our Style Guide” or “Write procedures for our Company Procedures”. Our employers expect from us to create or maintain our own rules of practice. In other words, a part of our job is to define and document how we are going to do our job. The moment occasional writers discover this is the moment they consider the job “not that simple”. Our procedures, other people’s procedures, our rules, anyone else’s rules, it is all technical content and it can all become our responsibility in any organization. 

Now let’s remove redundancy and overlap, and simplify a bit.

Figure 2: Artifact-related common tasks regrouped

The purpose of Figure 1 was to give an idea of the diversity. Figure 2 is much closer to the general idea of what we do. It is reassuring to see that a group of offers does present an image of complexity, it means our employers are aware of that aspect.

The grouping of the “medium” column under three labels is arbitrary, it is the result of my own choices. To me, internal audiences and external audiences are fundamentally different, and these categories reflect that. Also, in some situations, the technical content is integrated to a knowledge system, like when we use tooltips for example. In that case, the use of or documentation is tied to the use of the system. That distinction is weak, I realize that, I need to work on it some more.

But that is not all of the common tasks that are required of us. There is also the following:

Figure 3: Other common tasks

We have to collaborate with a bunch of people. I think the best Technical Writers like that part. And of course there is the interaction with the audience. More about that in later posts.

Rare tasks

I call them “rare” because they are rarely mentioned in the selection of offers, not because we do it rarely. In fact, I would like to promote some of them as high-priority tasks. There are several reasons why we don’t see them often mentioned by employers. I think the main one is they don’t see them as part of our mission. Another reason is they don’t like them. Maybe the tasks are hard to control, or are seen as causing unjustified spending.

I have spotted 14 of them in my sample. I won’t provide a development for each of them here, however some of them will get their own post later.

First a few aspects that are essential part of Technical Writing practice. I would like to know 1) why most of our employers don’t mention them and 2) why some of them do. My hypothesis is they don’t want to be aware of it but some had the experience of those tasks being neglected and now they want to make sure those boxes are ticked.

Ø Develop a thorough understanding of the audience and the documentation required.

Ø Estimate level of effort and manage priorities.

Ø Verify correctness and accuracy of all the content.

Ø Assess existing Technical Documentation (with Project team for documentation and Sales for marketing content).

I did see a couple of missions only dedicated to an assessment of existing documentation, though. It is one of my favorite things to do.

Some support roles:

Ø Advise project teams to create high-quality and usable content.

Ø Support Marketing communication for the core concepts and values of the product.

Ø Define the content strategy that supports the company strategy.

Ø Address new market opportunities.

We mostly work with Engineering. Mostly. But we see here that Marketing also needs us. Collaborating at the same time with Engineering and Marketing, who usually agree on nothing about what the other one writes, is always entertaining. In any case, I believe the tasks presented above need much more love than they have right now, in the sense that the Technical Writer may be the best ambassador for content consistency throughout the organization and all across the customer journey.

Ø Conduct research on technical product-related topics.

Ø Report any customer feedback for possible feature requests or for issues.

Ø Create templates and examples for product adoption (internal or external)

Ø Learn about autonomous systems, simulation, reinforcement learning, and machine teaching.

We have here a couple of things related to the relation between Technical Writer and UX, that I will develop extensively in other posts. Then the notion of product adoption, which I know quite well, associated here to “templates and examples” but product adoption can be a global effort through all of your documentation system. Finally, this little gem about “autonomous systems” and family. This is not about AI as we hear about it today. The offer was from 2020 when no one talked about AI, as compared to now when everyone does. This here is more advanced: I think it is part of the future of Technical Writing. More on these topics in future posts.

The remaining two tasks deserve their own comments.

Ø Deliver under tight deadlines with minimal revisions.

Whatever we do, we WILL have tight deadlines. In our line of work, especially in the software industry, deadlines are so tight that we hear the terms “yesterday” and “last week” very often, even if our Product Owner is not a drama queen. What worries me in this task description is the addition of “minimal revisions”. Our work’s quality depends on our content being verified by our sources. If you see this, you need to check if you’ll work under a hierarchy that expects you to write pieces that don’t need revision. If so, then you may want to keep looking. I’m just saying.

Ø Interact to customers to point them to the right online content on our portal.

Now, I didn’t keep the offer context for that task, so I may have the wrong idea, but if we need a direct interaction with customers for them to be able to navigate in the online portal, we have a major issue on our hands. We exist to fix that. Every interaction with customers should be used to find a way to make the need for assistance disappear. Otherwise, how could you scale? Instead of this request here, one of our tasks is to make sure that the audience can navigate in the documentation and find what they need when they need it. My advice: if you see that task, don’t sign anything.

Are you still here? Congratulations! It was not my intention but some time has passed since I first wrote this piece and I now have the opportunity to examine two dozen job offers from American companies published in the course of July 2024, and compare. That is four years, has anything changed?

Remember that this is qualitative: there is a probability that the change we see between my two samples are the result of natural dispersion of results and not of underlying trend.

Observations on the second sample

I don’t remember if it was the case for the first sample but announcers tend to concatenate a lot, the result being each description of task containing multiple tasks. From 22 offers, I extracted about 400 tasks. And in a few cases (6 of them), the task was something along the line of: “perform any other assigned task”. I confess I have mixed feelings about that one. At least they acknowledge there may be… unspecified stuff.[3]

My first observation is that job offers today seem much more boring than a few years ago. We find all the common tasks, except for the taxonomy-oriented, but almost none of the rare ones. For the common part, it seems more process and procedure oriented than before. Again, this is just one month in the year, maybe it is seasonal. In any case, the part that I grouped under the “common tasks” label appear pretty solid and long-lasting.

Among the less frequent items, we have the following:

Ø Manage and maintain the global repository.

All that content that we put in this or that artifact, has to be stored somewhere. As versions come and go, that repository grows, and is sometimes used by a whole team. It has to be managed. It is part of every mission, but it is rarely mentioned.

Ø Analyze and document the code base.

In the software industry, some documentation systems and processes are very close to the code, especially when the methodology named “Docs as Code” is used. Sometimes, there isn’t even a methodology. I’ve been told once: “the code is well documented, you can find all the information there”.

Ø Stand as product expert.

Most employers, most colleagues, and many of us Technical Writers believe that being a good Technical Writer requires that we become expert in the thing we document. I consider it a misconception, and I would not go for a position where you are supposed to be Tech Writer and SME (Subject Matter Expert) at the same time. I will write a specific post soon to explain why.

Ø Design and develop data collection tools and methods to measure the impact of training.

This should be part of any mission involving the creation of training content. Students are evaluated at the end, and so should the training itself. Building training content is one of my favorite things to do.

Ø Appropriately assess risk when business decisions are made, demonstrating consideration for the firm's reputation and safeguarding its clients, and assets, by driving compliance with applicable laws, rules, and regulations, adhering to Policy, applying sound ethical judgment regarding personal behavior, conduct and business practices, and escalating, managing and reporting control issues with transparency.

Now this one is special. It was part of the list of tasks in a Technical Writer position offer, but it looks like something a company could ask from all collaborators. There was the notion of “responsibility” also mentioned somewhere else in the offer, that is consistent with this. It is a complex proposition, and looks like a legal safeguard, but I like the part where we are required to consider the strategic value of our choices, it gives more weight to our role in the long-term success of the business.

I should mention that none of the offers in this sample mentioned AI-related tasks, although I’ve seen a few in other offers I’ve read before or after I collected these. It is surprising because today (summer 2024) AI is all the rage in Technical Communication circles and has been for about a year. I guess it is still time to get those specific trainings and courses you heard about[4], so you can add one or more years of experience with AI-powered systems on your next resume, for when employers will require them.

I thought I would find more differences between 2020 and 2024. It seems the main change is a change of style: it feels like our profession is still perceived the same way, but the offers themselves are written with less care.

And now I wonder: does this plethora of activity items give you a better idea of what we do? I must admit, even though in all the companies I have visited, I have met very few non-Technical Writer people understand what we really do, when I regroup all these tasks I see a surprisingly convincing image of the profession. Diverse, deep, connected to the field, connected to the people as well, strategic.

But this is too much work! I cannot imagine anyone starting to list all the things we can do whenever someone asks “What is Technical Writing?” Besides, this is all about the execution, what about our purpose? Can’t we find a more convenient answer?

The beacon-in-the-dark definition

One of the problems of a task-oriented definition of our profession is that each time a new kind of object or action comes up, we would need to redefine what we are. Actually some of us do, especially if they take our label “Technical Writer” literally. There is some pressure to change that label for “Content Strategists” or things of that nature. We'll go deeper into this someday, but for now let’s just accept that we can put under the label “Technical Writer” just as much meaning as we want.

I think it is a mistake to let the result of our work define our function. The way we accomplish that function is to create a certain type of content, but if we let that content define us, then we incur the risk of keeping on making content that really does not serve our purpose. We could do that forever without even thinking of checking if we are of any real use.

That was a bit obscure. Let’s clarify. The way I see it, Technical Writing’s purpose is to help people do things or make decisions by providing knowledge artifacts. That is what we do. The fact that we do it through artifacts sets us apart from teachers or trainers. We don’t directly interact for transferring the knowledge. A way to say it is the transfer of knowledge is asynchronous. Day one, we write instructions, day 2 to 1200 people read the instructions if they think they need it, and apply them if they feel like it. They do it whenever they want, as much as they want.

Traditionally we provide the knowledge in written form, which is why we are called “Writers”. We started doing it when there was so many people to help that training or mentoring was out of the question.  At that time “audio-visual”, that was later called “multimedia”, and is now just called “video”, was difficult, expensive, not very well known, so we would write. Today I think we are coming back to audio-visually-based mentoring in the form of billions of videos called tutorials, guides, and other walkthroughs, but that is another story. My point is we usually write, but we can use other means to the end that is helping someone with knowledge.

In many cases, the knowledge we provide is technical, because technical is often complex and complex calls for more assistance. But what we do applies to any type of knowledge, even on very simple concepts or processes.

It is very easy for us human beings to forget we help someone and instead of that we focus on the most complete possible description of the object we are documenting. Not just because we are lazy. There is above all the fact that we tend to focus on tools instead of the activity they serve, or instead of the objective they help reaching. There are a few psychological reasons to that and I am not going to develop them now; just think of the tendency we have to think that if we buy the best tool on the market there is no way we’ll do a bad job. Or think of the way we believe that if we stick to every aspect of a given methodology our projects must always be successful. We tend to forget the ultimate objective and in the case of Technical Writing, the objective is helping someone do a better job using the thing we document.

I believe it is necessary that we remember our purpose. Here are a few reasons:

-      If we state our purpose, we don’t need to draw the complete list of how or with what we accomplish it. All those things derive from the objective. Our techniques, the tools we use, the rules we follow, the types of artifacts we create, all of that is part of how we fulfill our mission and can be described separately. That is a good thing, because: 1) the list of “characteristics” is never-ending and for some of them we may have disagreements; 2) as time goes by some items in this list are replaced by better ones, and it doesn’t change our purpose; 3) in some cases we face exceptional situations where some items in the list take us away from the objective rather than closer to it and in this case we should abandon those items.[5]

-      We can create knowledge artifacts that correspond on all counts to a characteristics-based definition of our work, like for instance a manual that “informs, instructs, or directs a specific audience through maximum clarity and precision with a specific tangible goal in mind”, as prescribes the example definition we have seen above, and still fail to help our audience with it. For what I’ve seen, it may actually be very common. I call it the syndrome of “excellent documentation that helps no one”. We forget the objective. Let’s define Technical Writing the right way so our purpose remains in front of our face.

-      Our purpose aligns with business objectives. If all we do is “produce that kind of document, that way with that tool, following those rules”, of course the organization we do it for will see it as just another cost-generating activity. If we “help that population do that thing better with our tool”, it is much easier to follow with the reasons why that objective is better for business. Helping these people is good for business for these reasons, helping those people is good for those other reasons, etc. We are then part of the business strategy. We can back up requests for resource with arguments that make sense for the persons we ask it to[6].

-      My favorite reason. If we’re not fixated on the content we create and how we do it, but instead on what that content is for, we can at all times verify if we do a good job. The biggest danger of “excellent documentation that helps no one” is that we know it is “excellent”. It follows all the rules, it is clear, consistent, etc., as experts it appears beautiful to us. We have no reason to alter it. How about we just, every once in a while, check if it reaches its purpose: let’s see if it helps the audience do better than without it. The other side of that argument is that when we are guided by our purpose, we are never wondering what to do next, how to improve, in which direction to develop: we investigate what the audience is doing with our work. We find all the answers there. We want to help that group doing that activity with that tool, for these business reasons; if we wonder how, let’s go out there and find out! I created a course for helping you out on this, by the way…

I call this definition the beacon-in-the-dark definition because it actually guides us when we don’t know what to do.

Technical Writing is helping people do things or make decisions by providing knowledge artifacts.

To achieve that, we use the techniques, tools, rules that are the most appropriate to the situation. In most cases, the standard rules we follow are our best option, but with our purpose in mind, we can detect when it is not the case, and react accordingly.

What do you think? Does this help understand what Technical Writing is? Is it a real guide, or just another grail-shaped beacon that is just a lure? Go ahead and comment if you want to share.

---

[1] That should NOT console you.

[2] I intend to address our obsession for tools a few times on this blog.

[3] I have to say it. This task does summon in my head the image of a boss adding, at the end of a long list of duties, “Also, be my bi*** all the time.” But that’s just me, past experiences, etc.

[4] I have to recommend FireheadTraining.

[5] For example, we can consider that our content must be detailed and comprehensive and then meet a situation where being detailed and comprehensive makes the content less usable to our target audience.

[6] It hurts me to say, but sometimes we create documentation that has no point. The business feels obligated to provide it, and does it with so little care that in the end the result is no help at all, to a point where it damages the customer’s trust. So everyone would have been better off creating nothing at all.