avatarChloe Ip


3 Skills Every Good Tech Writer Should Master

Excelling at these three skills will help you craft stellar documentation.

Photo by Kaleidico on Unsplash

Here’s the truth about being a technical writer: nobody wants to read your writing.

But you’re convinced you want to do it anyway because you fundamentally know that good documentation complements well-developed software programs. In other words, documentation is not an add-on; something ornamental or decorative.

It. Is. Essential.

And you’re convinced you want to be a tech writer because you’re intrigued by the world of user guides, manuals, FAQs, and quick references.

In short, you’d like to know what skills you’ll need to write excellent documentation.

Teaching (or the art of performance)

One of my translation professors used to drill that writing is performance. A music teacher I read advised that the worst thing a performer could be on stage was to be boring.

As a tech writer, you’ll be providing solutions through writing. So if you’re writing, you’re performing, and if you’re performing, don’t be boring.

You read it correctly: making your user guides interesting to read is important. Be empathetic and imagine being in the user’s position: how many of us wake up in the morning thinking I can’t wait to read that user manual on installing curtain rods?

You’re right: nobody.

So, what are some ways to hold your user’s attention while you teach them the solution to their problem?

Be Direct

The reader is reading your material because they’re stuck on a problem. Assume they want to get in and out of your manuals as quickly as possible. So, give them what they want (i.e., the solution)—right from the start.

Be the User’s Friend

Your guides are your user’s ally. Firstly, the user could be tackling a problem perceived as threatening. Helping them to see the situation through something they’re already familiar with can bridge the gap between frustration and relief. Can you invent a metaphor or analogy that would tie the user’s experience to the product and make them see it as a friend instead of a foe? What story can you weave into the product that makes them identify it as a positive extension of themselves?

Being able to incorporate the people you’re writing for into the narrative could make them more receptive to the guides you created for them — and convince them to read it if they’re facing a problem you documented a solution for.

Being Paranoid (or Anticipating User Needs)

Being semi-paranoid helps immensely in tech writing because you’ll be reading, parsing, digesting, synthesizing, and reformatting — a lot. This means you’ll need to be critical about what you decide to document; you need to think for your readers.

For example, find out which keywords readers will use when searching for your documents. Does your product use a special vocabulary that makes searching for general keywords ineffective? Is the material best presented through text, video, or both? How would you determine which users want which format?

The Golden Tech Writer mantra is worth repeating: no one wants to read your writing. Users read your guides to solve a problem that’s blocking their progress. They want a fast and convenient solution to get back to their actual task. They don’t want to look for a solution to a problem that shouldn’t have (in their minds) materialized.

Therefore, your ability to decide what is critical and what can be omitted in the docs is a skill. The ability to present the crux of the solution is a talent.

The critical question to remember is this: can the user quickly find the solution they need, and will it solve their problem?

Gaining Telepathic Skills (or Predicting Where Users Will Fail)

Part of being a tech writer means being a little psychic. In other words, you’ll spend a good chunk of time anticipating user needs because your users will inevitably run into problems with the program. Ask yourself how you can document the task that gives the user the best chance of succeeding. Another way to put it is how you can make sure the task is challenging to fail at.

Remember: if your user is reading the docs, it means they need help. They were probably in the middle of doing the task when they had to stop, search for your guide, and spend time reading something they didn’t want to read. On the thermometer of frustration, bitterness, and resentment, the levels are rising quickly, and the last thing a tech writer wants is someone reading their guide and not getting the help they need.

That is just a bad performance. Period.

Being a tech writer is starting to sound a bit stressful, eh?

But when your users find the solution they need while reading your manuals and write you a note telling you how easy it was to follow the manual, the pride you’ll feel would be worth it.

That is how most tech writers stay sane, which leads me to the next point about how they maintain their sanity.

Staying Sane (or Writing Without Putting Your Mental Health on the Line)

User guides change constantly because the product is continuously being updated. That witty metaphor you invented to describe that annoying feature you diplomatically suggested to the developers to remove? Well, maybe the developers finally heeded your wisdom and removed that annoying feature — after you had already documented it. Thanks to you for that ingenious solution for that labyrinth of a process that all users were getting stuck on but became unstuck. Maybe management finally improved the process, and now your docs are irrelevant.

So, how do you avoid becoming sociopathic by cutting up your writing?

The answer is acceptance.

Accept that your writing is temporary, always ready to be erased, diced up, or surgically removed. It’s pretty liberating when you accept that your writing is ephemeral, evanescent, and short-term.

It’s a bleak picture of the tech writing world I'm painting.

But you’ll be the one feeling proud when your work helps somebody else get their job done—and on time.

So, even if your documents are shredded afterward or become lost in cyberspace forever, remember that you wrote them.

That you got paid to write docs.

Better: that you got paid to write.

Career Advice
Technical Writing
Effective Communication
Software Documentation
Writing Advice
Recommended from ReadMedium