Tech writing: The subtle art of being there and not there

My objective as a writer is for people not to notice me. Not because I have social anxiety or nothing to say, but because that’s the kind of communicator my audience needs me to be.

I’m a technical writer at a software company. I’m there when a new button is born, when there are functional errors and design triumphs, and when a feature takes its first tentative steps into the world. Like other user experience specialists, it’s my job to help the customer discover, learn, and work with ease. But I don’t want them to be aware that I’m doing it.

So I work to minimize my writing “footprint” and use communication strategies that prioritize their need to know over my need to be heard. I’m not trying to give them a great reading experience, I’m trying to give them a great product experience. Here are some of the techniques I use to do this.

Communicate in a straight line

Communication is the successful delivery of a message; writing is just a vehicle for messages. I know how trite that sounds, but it’s not my aim as a tech writer to impress people with my writing prowess, it’s to communicate complex things (using words, graphics, video, and diagrams) in a simple way, and minimize interference.

Interference causes the reader to hesitate and think, “Am I doing this right?” or “What’s the next step?” They may also have to read things twice (or more) to understand, which undermines their confidence and creates a bad experience of the product.

Why make them read this:

When they can read this:

Try to spend all your writing energy clearing a path for the user, removing obstacles, and creating more certainty. Question the usefulness of every word you use.

Think situationally

Empathy is a big part of communicating, and understanding the needs of the user in a given situation is critical to selecting the best approach.

When someone needs help problem-solving, draw the shortest possible line between point A and point B. Deliver unembellished information that is direct and helpful. Do X, then Y, then Z. No fluff, no “value adds.”

When a person is doing a task for the first time or they need a reminder, take them in a straight line — but also describe some of the landscape. Use concept explanations, tips, shortcuts, and other supplementary information that make doing and remembering the task easier.

Users learning a process for the first time need things to be more “sticky,” so it helps if you can build a story around the what, how, and why of the topic. Most people want to relate, so telling a familiar story will make learning a lot easier.

Communicating in a straight line is the best way to help a user, regardless of the situation. Try to create a flat, familiar journey for every kind of user.

Know when to shut up

To communicate something complex, you need to have a full picture of the process, the concepts, the use cases, the “whys,” the “hows,” and the “whens.” Only when you have all that can you make a good decision about what information will help and what information will hinder. I spend almost as much time determining what to leave out as I do on what to put in. There are some principles that can help with this “iceberg” approach.

• Write for the majority — Determine the “happy path” and work from there. If a certain process works for 85% of cases, then write to that one. Acknowledge, but don’t write for edge cases.
• Question everything and everyone — Question your subject matter experts thoroughly. How does it work? How is it accessed? What is it for? What can go wrong? What does a user do if…? What if X? What if Y? Keep asking and asking. The more you know, the less you write.
• Group and label effectively — Don’t waste the user’s time by making them read information that does not apply to them. For example, don’t write steps that repeat “do this if you are A, and do this if you are B.” Instead, set out clear preconditions for situation A and situation B, then write common steps.

De-fluff your stuff

Like it or not, the world is full of fluff. This is great for baby animals, but if you’re a frustrated person trying to do a task, fluff is the infuriating, unnecessary stuff that keeps you from doing what you need to do.

Fluff is more than under-edited writing that slows reading, it actually adds to the cognitive load. De-fluffing is about readability and accessibility, so avoid these:

• Vagueness — If you don’t have all the facts, or if you’re trying to be too “inclusive” of audiences, messages can end up vague and unhelpful.

• Inconsistency — Decide what something should be called and stick to it. Avoid using multiple words that mean the same thing. Decide in advance if you’re going to use “application” or “program,” “choose” or “select,” “help” or “support,” etc. Unless you write crime novels, don’t shift meaning around on your reader.
• Jargon — Jargon is the language of products, not actions; it’s all noun and no verb. For instance, I don’t care if my car has a catalytic converter, as long as it produces fewer emissions.

Don’t over-parent

When writing about complex things, it’s easy to over-explain. This normally manifests in warnings, notes, pre-requisites, and explanations before actually telling the user what to do.

It’s kind of like over-parenting; you think you’re keeping your child safe by warning them to “be careful,” but you’re actually making them fearful of what’s around them or being a buzzkill. Either way, you’ve interfered in their experience and given an “edge case” much more weight than it should have.

Like kids, users also need exactly the right amount of support and the right amount of scaring. But, only point out risks based on the likelihood of the problem and the proximity to it.

Be part of the product experience

Here’s a handy way to test if a design or feature is user-friendly: ask the tech writer to write about it. If it’s hard to explain, then it’s probably hard for users to understand. And that’s the tech writer’s end-game: to help users understand the product through great design communication.

We want them to see familiar terms in the user interface, to click buttons with confidence and get their work done without ever looking at a document. I don’t want them to need me, or know I exist.

One way to do this is to show, don’t just tell. Images and .gifs can show what it might take a paragraph to explain.

Click to copy other people into the email.

Maintain the care factor

If I had a dollar for every time someone said “Nobody reads the documentation anyway,” I’d have enough money to retire from writing documentation. I have news for anyone who’s ever said that: I KNOW. But that doesn’t mean people don’t need it or use it. It just means it’s not meant to be “read”… at least not as your preferred bedtime reading.

When was the last time you read an entire website? Likely never. But if you want information from that website, you expect it to be there, in the right place, in the right words, fulfilling your need. I know people don’t read in whole pages, or even whole paragraphs, but what I write still needs to exist. And with complex software or products, people really need the info to be useful.

I wish we did live in a world so well-designed that everybody just “knew” how to use things, even complex things. But we don’t. So writers are necessary to help people understand how things work.

We might be the invisible ones, but we have a lot of control. We can take users the short way or the long way to understanding; but hopefully it’s always the easy way.

Did you enjoy this post? Want more of the same? Consider following Designing Atlassian.