7 Technical Writing Dos and Don’ts

Last week, I blogged about five of the technical writing tips I’ve picked up along my journey—both as a student and as someone who’s written a number of technical documents throughout her career.

This week, I’m here to take it a step further, detailing some technical writing dos and don’ts.

Here they are at a glance:

Technical Writing Dos:

• Do anticipate what your audience already knows—and will need to know.

• Do rely on subject matter experts (SMEs).

• Do define your scope of work.

• Do have someone review your work.

Technical Writing Don’ts:

• Don’t assume.

• Don’t use language to “seem smart.”

• Don’t forget to cite sources.

Let’s start with the dos.

Technical Writing Dos

Do anticipate what your audience already knows—and will need to know.

Think about some of the technical documentation you’ve read.

Perhaps it was a manual with instructions to assemble 46 pieces of wood to build a bookshelf. Did the manual make the job easy? Or did you find yourself on page 15 (and yet, somehow only step 3) wanting to rip your hair out?

A lovely wooden bookshelf—that just so happens to be the opposite of the bookshelf I recently put together (thanks to poorly written technical documentation).

If it’s the latter, please do all of humanity a favor and keep your documentation audience-friendly. 

You have to know your audience. You have to know what they already know, what they need to know, and what you know they need to know, but maybe they don’t know they need to know.

Alright, enough of that.

Point is, you should take the time to anticipate what your audience already knows about whatever it is you’re writing about. Whether your documentation explains how to build a bookshelf—or how to install software—make sure your directions are thorough enough to not leave your audience in the dust—but not so thorough that you’re on page 15, step 3.

There’s a fine line, and as a technical writer, it’s your job to find it.

Do rely on subject matter experts (SMEs).

Confession: When I first started writing technical blogs for Huntress, I had no idea what I was doing.

I was not only new to the company, but I was also new to the field of cybersecurity.

To speed up the process, I read and Googled and researched—but I also reached out to the SMEs we had internally to bring me up to speed on what I needed to know.

You can’t explain something that you don’t understand. Your first step is knowing your topic inside and out. SMEs can help you get there.

Do define your scope of work.

This is particularly true when writing instruction manuals.

Your readers should know what they can expect to accomplish by reading your documentation. If it’s building a bookshelf out of 46 pieces of wood, set that expectation from the very beginning. 

You’ve seen it before both in manuals and even YouTube how-to videos:

By [watching this video or reading this manual], you’ll learn how to build a bookshelf using the supplies in your kit.

You’re setting up your audience for success by clearly defining your scope of work. They’ll know the end result ahead of time and can work toward that—much like seeing a picture of an assembled jigsaw puzzle while assembling the pieces to solve it.

Do have someone review your work.

It’s a humbling truth: Just because something makes sense to you doesn’t mean it’s going to make sense to others.

Both with technical writing and any other kind of writing, it’s always a best practice to make sure your writing makes sense to others. Much like my peanut butter and jelly sandwich example in my last blog proved, a common sense step to you may take someone else by surprise. 

Having others review your work can help you make sure you haven’t overlooked any details. Even better, you’ll be that much more confident that your instructions will make sense to your audience.

Technical Writing Don’ts

Don’t assume.

You know what they say about people who assume.

At the risk of sounding like a broken record, it all goes back to analyzing your audience—knowing who they are, what they need to know, and what they don’t yet know. 

For example, it may be tempting to assume that your audience knows the exact end goal of reading your documentation. Don’t fall into that trap. Clearly outline the end goal in your scope of work, and ensure your audience knows exactly what they can expect after following your instructions.

Don’t use language to “seem smart.”

We’re taught from a young age that big words mean intelligence, authority, and wit. 

That’s just not true—especially when it comes to technical documentation.

Technical documentation shouldn’t be needlessly technical.

Sure, you may not be able to substitute every single term that the average reader may not understand, but if you can’t, be sure to spend extra time defining those terms. And when you go to define those terms, make your description as easy to understand as possible. (Analogies work really well for this.)

Use simple terms when you can—and when you can’t, simplify your explanations of those terms as much as possible. Your readers will thank you. 

Don’t forget to cite sources.

This is surprisingly one of those steps that many people tend to miss.

If you rely on an SME to fill in your knowledge gaps, credit them. Read an article to help you write your documentation? Cite it. Use an illustrator’s image to help you define that super tricky process in step 15? Cite it.

Doing so validates your work and lends it credibility. It also lends you credibility as a strong technical writer.

—

These are the best technical writing dos and don’ts I have to offer. Many of these will feel like second nature as you get the hang of the art of technical writing. Practice often, and refine your work. You’ll be an expert in no time!