5 Technical Writing Tips for Good Technical Writing
Technical writing is the art and skill of distilling technical content to non-technical audiences. Examples include user manuals, white papers, reports, standard operating procedures (SOPs), press releases, and even internal company documents.
To be a technical writer, you have to understand two things:
The topic you’re writing about
Your audience
Once you understand your topic, you can explain it to others. And once you know your audience, you’ll know how to explain it to others.
Technical writing use case
Say you’re writing a guide on how to remove malware from a computer. First, you’ll need to understand malware, how it works, how to find it on a machine, and ultimately how to remove it. Once you have that understanding, you’re halfway there.
Then, you need to know your target audience. Are you explaining these steps to a typical computer user who may not know what malware is? Or are you writing a guide for seasoned cybersecurity professionals who may just need a refresher?
One of these audience groups will require far more detail than the other, and it’s up to you, the technical writer, to meet your audience where they are.
I became a technical writer by accident.
I was in my early 20s when I walked into the registrar’s office at West Virginia State University. Bright-eyed and bushy-tailed, I told the registrar I wanted to major in English.
“I see. Which of these concentrations do you want to pursue?”
I looked down at the piece of paper she slid across her desk.
Professional writing, literature, technical writing.
I took a beat. I’d only ever known about general studies, having just earned my Associate in Arts degree at a community college.
“Well, professional writing sounds a bit…dry,” I said. “I like to read, and I don’t want college to ruin that for me. Let’s do technical writing.” I checked the box with my pen and passed the paper back to her, an unsure smile forming across my lips.
I chose my major having absolutely no idea what technical writing was.
5 Technical Writing Tips
I’ve written a solid amount of technical documents throughout my career. As a result, I’ve picked up some good tips along the way.
Here are my top 5 technical writing tips that will put you well on your way to becoming a good technical writer.
Technical Writing Tip #1: Start your documentation from the very beginning.
Good technical writing always starts from the very beginning, identifying what the user will need to complete the task you’re about to explain. Be careful not to inadvertently skip steps, as this could lead to a lot of end user frustration.
My college professor taught me this in an assignment I’ll never forget. My first technical writing project was to document how to make a peanut butter and jelly sandwich.
I was so proud of my finished documentation. I remembered to list all the ingredients, all the utensils needed, and even remembered to insert a “caution” if you chose to use a knife (more on cautions in a bit).
Explaining how to make a peanut butter and jelly sandwich is a great technical writing exercise.
I explained how you’d gather your materials, delicately hold the bread in one hand, apply the peanut butter and jelly oh-so-carefully on each respective slice of bread, and then put the two slices together—even noting which sides of the bread should be touching!
But you know what I (and all of my classmates) forgot to mention?
Opening the jars.
That first, critical step completely slipped my mind—but this assignment and the lesson it taught me sure haven’t.
Technical Writing Tip #2: Introduce one instruction per step.
We’ve all read instruction manuals that chunk out multiple instructions in a single step. And before you know it, you’re eight lines in and only on step one.
That’s frustrating.
Your technical documentation should include only one instruction per step. Begin the step with an action item, and finish the thought in a single sentence. If you need to elaborate, create a sub-step. Use those sparingly.
Technical Writing Tip #3: Call out any cautions/warnings ahead of the step they pertain to.
Nothing’s worse than a late caution or warning.
In our peanut butter and jelly sandwich example, users need to be aware that they could injure themselves if they choose to use a knife. But they need to know this before they pick up the knife. Note any warnings or cautions before the step that introduces the potentially dangerous action so your readers will know to exercise caution before they start that step.
Not only will properly placed cautions and warnings make you a strong technical writer, but they’ll also make the lawyers at your company happy.
Technical Writing Tip #4: Eliminate jargon.
Remember in school when they taught us to use fancy words with multiple syllables to prove we’re well-read?
Turns out, that’s garbage advice.
Keep your writing as simple as possible. Be concise, and use simple language.
If you have to use a term that the average reader may not understand, define it. If you have to use an acronym, spell out what it stands for on the first mention, and list the acronym itself in parentheses. This will help your audience understand the term moving forward.
Technical Writing Tip #5: Clearly label figures and refer to them in your text.
The best technical documentation has easy-to-read diagrams and figures to give you a visual of how to complete steps.
Make sure that your figures are labeled (e.g., Figure 1, Figure 2, etc.), and call them out in your documentation (e.g., “See Figure 1”). This will help your end users tie your steps or instructions to their corresponding visuals. Your goal is to make your documentation as straightforward and easy-to-follow as possible, and creating this link between your copy and your figures will help to accomplish this.
—
I hope these 5 technical writing tips are useful to you in your own writing journey. With enough practice, dedication, and mistakes (e.g., forgetting about those pesky lids), you’ll be a sharp technical writer in no time.
Updated 2/12/2024