Shape up or ship out: let's talk about technical writing

Let's talk about technical documentation and what a good tech writer does day to day. The job means bridging two worlds. On one side is the client, who wants to write down everything to promote their business and brand. On the other is the customer, who wants it explained as simply as possible. How do you serve both? Where do you draw the line?

I write documentation for a living, so here is the advice that helps me. Use it and the next time you ask a customer "Did you read our guide?", you won't get a "TLDR" in return.

The first thing to nail down is what the client actually wants. Some care about the sheer volume of documentation; others want a small amount done well. One client targets their existing customers, another is chasing fast growth in new ones.

Here is how I find out:

This part can get complicated, but try to think like a customer and walk through your own guide step by step. You will find that things you thought were obvious are not. Watch every word, and use the same phrases and naming the whole way through.

It also helps to ask a friend in the industry or an experienced consultant to read it. They catch problems you stopped seeing a long time ago.

If you are writing a more complex guide that walks through a setup step by step, add a "test it out" section. It shows that everything works and that you ran the setup yourself. That reassures customers, especially if you record the test on video.

Your guides get read by customers all over the world. Keep that in mind before you reach for a complex phrase or a long sentence. Idioms spice up the text, jargon makes it feel familiar, and buzzwords read smoothly, but in tech writing, simpler wins every time. (Yes, I am using idioms in this article. I just can't get away with them anywhere else.)

Walls of text. Long sentences explaining the problem in detail. Hard to follow when you read it. Sound familiar?

Keep it simple and draw what you are describing. A diagram of the flow helps the user see what they will get if they follow the guide. A UML diagram works well here.

Images have served me well, and so have short video tutorials with narration. It is not just my experience. According to a study by Adhan Kholis of the Department of English Language Education in Indonesia, students do markedly better when lessons use video or images. About 90 percent of the information we take in is visual, and the brain processes images far faster than text.

These elements break up long texts and make the whole guide easier to follow.

Feedback is everything. Take it well and make the most of it. Good people to ask:

Feedback from people matters, but it is not always reliable. As a rule, people don't like to give negative feedback. You can read more about this in this article.

TIL: Why is it so hard for people to give and receive negative feedback?

The usual answer is our negativity bias. Psychologists and neurobiologists have found that our brains are wired to react to negative stimuli faster, which once kept us alive. Sensing an attack triggers fight or flight, floods the bloodstream with adrenaline, cuts reaction time, and heightens emotion.

So lean on hard data from analytics as well. It tells you how many people read your guide, how long they stayed, and where they went next. Most useful of all for a tech writer, it gives you feedback without the human factor.

Learn from your mistakes and from the questions that keep coming back. A knowledge base keeps that knowledge inside the company. The people doing technical support love it: give them a place to store what they learn and you save time and the client's money. Everyone wins.

Learning these rules takes time, for the client as much as for you. But it is better to be honest and spend the time on a quality result than to slap something together in a hurry.

A real project takes more than copy and paste. To build trust with your client, find common ground and borrow what works from this advice.

You might also be interested in:

Sources: