The importance of audience, or, how to scale a tech writing team

A recent experience brought home to me how important it is to take account of the audience of a document. It also showed me how a well-tailored doc can help people perform tasks that they may need to do only rarely, but that are highly important when they do need doing.

Here’s the story, which you could entitle, The importance of audience, or, how to scale a tech writing team, or, how to encourage engineers to write documentation.

Over the last few weeks I’ve worked with a small tech writing team to create a documentation set for a product launch. It was a highly technical product where, by necessity, engineers wrote much of the material. In particular, we provided a number of tutorials that show customers how to run specific, optimised machine learning models, and we published best practices for people who want to customise the models.

In the leadup to the launch, new tutorials and updates were coming in thick and fast. Too many for a small tech writing team to handle. We needed the engineers to write the initial versions of the docs, and to send them to us for review and publication.

So, we needed a guide that would help the engineers write docs for our documentation site.

Now, of course, we already have plenty of guides for tech writers, telling new team members how to use the various editing and review tools. You’d be tempted to point the engineers at those guides and say,

“Go, do the same.”

That doesn’t work too well. The engineers tend to get lost in a sea of documentation that doesn’t answer their questions.

TL;DR: The audience is different.

• New tech writers need to know how to use all the editing and review tools, as well as the tools for publishing a doc on the test site, and the processes for reviewing and publishing changes.
• The engineers know most of the tools and processes already, since the docs are in the same repository as the code that the engineers work with every day. The editing tools and review tools are the same too. Even the source format (Markdown / HTML) is familiar. All the engineers need to know is:
  • Where to find the doc source, which is in the same repo as the rest of the code that they work with every day.
  • That the editing and review tools and processes are those they use every day too.
  • How to stage a doc on the testing site.
  • Who will do the doc review and publication.

To help the engineers get started quickly with writing docs, I patched together a very short guide containing the information outlined in the above four points.

The short guide also focused on command-line tools rather than GUI, whenever there was a choice. Most engineers prefer the command line, as it’s where they spend most of their time. Learning the peculiarities of a GUI for a task they’re not going to do every day is a waste of time.

The short guide worked a treat. We had plenty of high-quality material coming through the pipeline. The engineers and the tech writers worked together efficiently, fast, and happily. A very small team of tech writers was able to produce high-quality docs on time, and stakeholders were pleased with the result. I think the engineers had fun too.

Giving a specific doc to a specific audience works!

Of course, the trick is to find out who your audiences are, what they need, and which of them are worth the extra work of receiving a doc tailored specifically for them. Another post, anyone? 🙂