Signs that you need a technical writer

Soon after publishing Tips for hiring your first technical writer, some readers kindly suggested to follow up with a post covering the previous step in the tech writing journey, that is, the realization that one needs a technical writer. As there seems to be a strong appetite for this kind of content, I’m going to spend some words to list what I think are the most egregious signs that your team, company, or product requires a technical writer (or a tech writing team).

If you’re here reading this, you might belong to one of two groups: Either you believe that you need technical writers and arguments to defend the need for them in your team or you don’t know what I’m talking about and you’ve been sent to this blog by someone who does care about documentation. Whatever your group, you should be able to recognize the following signs in your workplace or project. If you do, it might be time to entertain the possibility of hiring a tech writer.

First though, let me open with a simple premise: If you’re shipping a product and that product is more difficult to use than a kazoo, you need the product to communicate to users through UX writing, docs, or both, and create a team in charge of executing the underlying content strategy. If nobody in there is heeding to the docs hierarchy of needs, that might be due to a lack of docs culture, ruthless focus on other aspects of product development, lack of funding, etc. It’s completely normal, and also sad.

Now, to the signs.

You don’t have docs to send people to

This one is easy to recognize: You have no documentation to speak of, or too little. Perhaps you haven’t had the time to write it yet, or writing docs simply wasn’t on your to-do list. No matter the excuse, the cold, hard truth is that there are no artifacts in or around your product that explain how to use it. As a result, you’re empty handed when users come to you asking for help.

It might not look so bad at the beginning, especially when you’ve few users or none, but as soon as you scale up, you’ll start to notice the pain of not having docs: Users not able to self-service and do things on their own will flood your support or sales channels with questions, increasing costs and delays. Even getting a certification or similar might become an impossible quest.

The time of your lead engineer impersonating Breaking Bad’s Walter White and yelling “I am documentation” is over. Get a technical writer or more on board, pronto. They’ll be quick to assess the situation and turn scraps of information into useful docs that everybody inside and outside of your team can use and contribute to.

You only have an FAQ and a README file

Frequently Asked Questions, or FAQs, are where good doc intentions go to die. FAQs are popular because they’re fast to produce, but they’re also the UX equivalent of a dumpster fire. If you’ve an FAQ in your website or documentation, it’s a clear sign that you need dedicated product writers and a content strategy.

README files in repositories, on the other hand, may be good while developing a product, but they soon outlive their purpose. When a product becomes complex and useful, its README file should act like a switchboard, pointing all kind of users to other documentation that explains things with care and detail.

“But my FAQ works!” you say. Of course it does: content always works compared to no content at all. The toy chest of my kids works as a storage solution, but it’s otherwise a chaotic, colorful mess that I wish a black hole swallowed forever. You don’t want to present a messy toy chest full of random bits to your customers.

You have way too many flavors of docs

When there’s no drummer in a rock band, there’s no rhythm. When there’s no content strategy in a company, content is produced randomly by the various rock stars in your band, with the ensuing cacophony. There you have customer support, sales, product, and marketing, all producing wildly different, overlapping documentation.

The lack of strategy and accountability of the situation I’ve just described is a sure way of harming a product. While it’s good that different actors produce documentation according to their concerns, the lack of a unified content experience and unified content management is inefficient and leaves customers angry and confused.

Getting a technical writer lead on board, or a content strategist, won’t automatically solve the situation, but it’ll ensure that someone will start pulling strings to bring all those content properties together so that they speak with a similar voice and tone and don’t sabotage each other in search engines. You need a maestro.

Developers are overburdened with docs tasks

Agile does mean having documentation, though nobody ever said who should be producing that documentation. Software developers often complain about having to write the docs, and they’re right: Documentation is hard to do well, especially when you have to do other things, like coding new features or squashing bugs.

It’s a pretty good excuse for docs-as-code tech writers, too (source).

Technical writers can not only free developers from docs tasks, but also support the team with testing, product management, and specialized coding knowledge. When they grow into devlings, writers bring lots of value to the engineering teams where they’re embedded.

Getting a tech writer on board is a matter of division of labor and specialization. There are many ways of becoming a technical writer (or promoting someone into the role), though it’s unlikely you’ll want to turn a developer into a full time writer. Instead, consider asking for a tech writer opening in your team.

You’ve found that UX writing isn’t enough

I love UX writing; I’ve done it a lot in recent years as part of my job. Some orgs and startups are also aware of the value that UX writing brings, and will go to great lengths to ensure that those Figma wireframes have good microcopy in them. The importance of UX writing cannot be overstated. And yet, it might not be enough.

Great UX writing can, and should, replace some user documentation. UX writing cannot replace all documentation, though, even when done from the very beginning of product development. It can’t because it’s not its purpose:  Docs focus on complex scenarios, concepts, and troubleshooting. All that is beyond UX writing’s scope.

When a tech writer works on embedded documentation, they can form strong partnership with designers and UX writers. A way of thinking about the difference between UX writers and technical writers is picturing the former as the front end and the latter as the back end of product knowledge and language.

Turns out your API isn’t self-explanatory after all

Picture this situation: You launched an API-based product with shiny new endpoints and HATEOAS. You think that your RESTful level 3 design is so clear that users won’t need documentation to make the best out of it, only to find out that users are, in fact, pretty lost about the very basics, like how to authenticate.

This happens because APIs are, as the name implies, interfaces. They’re special in that they’re made of words – think resource names, parameters, and so on. Those words are what enables the communication between applications and users of the API. The problem with words, though, is that they get confusing pretty quickly.

Tech writers can bring clarity to the usage of your API while supporting API design. They can create guides and examples, and curate reference docs that help tame the grammar and lexicon of your API. They can even choose the words that will become part of the API, thus becoming API writers. Quite a good investment, if you ask me.

I’m sorry, customers don’t really like your documentation

You worked hard to have your documentation up and running on GitHub. Or perhaps it’s Notion, or a bunch of Word files. It doesn’t matter: One day customers will tell you that the docs are inaccurate, hard to read, hard to find, or simply bad. It’s not your fault, though, because docs are a never ending effort that requires people dedicated to the task of keeping them alive.

Dumping knowledge in a place and forgetting about it is a misconception of product docs. Your product is a living, unfinished thing, and so is your documentation. You don’t just write a small book and then cross “docs” from your shopping list. Instead, you’ve to tend to the docs as if you were growing a delicate bonsai of information architecture.

The second misconception you’ve to get rid of is that the main job of a tech writer is writing. It isn’t. Tech writers organize content, test features, manage projects, edit existing documentation, do front-end development, investigate and fix the search engine on your site, and more. Everything that surrounds documentation is in tech writing territory.

Don’t feel bad about it, there’s a solution. That solution is called “hiring a tech writer”.