The best way to tell is to see if they go off on a tangent as they explain it. Otherwise, readers stay stuck in front of a piece of product they do not know how to operate — which means the client’s product simply doesn’t work!

Chapter 01: Technical Writing is not impersonal.

I hate it when technical writing is described as “impersonal”.

I write technical documentation that helps businesses maintain their product literature. I interview product managers, dig deep to know who they are, where they are, and what they aim to accomplish. Sounds pretty personal to me. Yet, it’s one of many incorrect labels thrown at a confounding field.

I like to define it as a style that: instructs, informs & guides.

This style of writing has its roots in the Puritan Plain Style, which dates back to the late 16th century. The Puritans believed in using short words, direct references to everyday objects to express their plain lifestyle. This style is used in technical writing, but it’s common in non-technical fields as well.

Maybe technical writers cannot dream up fictional worlds.

Or weave together intricate story plots.

But they do create helpful experiences for their audiences.

That takes vision and original thinking.

The process includes the same steps as most other styles:

— Brainstorming

— Research

— Drafting

— Revising

— Finally, Editing

Even though it’s shorter than other forms, it may actually take longer to craft because every word must have a purpose or it’s a word wasted. Still, there is a place for tone and emotion. Technical writing should be concise. But it should also express empathy, confidence, authority, and feelings.

Why do people read documentation? Because they need help.

Someone pulls over on the highway. He googles “How do I change a tire without a jack.” Now try to put yourself in his shoes and empathize with what he must be feeling — scared, frustrated, alone, and mostly helpless. If that’s how you just felt, how would you want to be spoken to? Like a robot?

Chapter 02: You are not writing for “normies.”

As a Technical Writer, I present info to not just users, but Engineers and Product Managers. When I pivoted from engineering to technical writing, I knew this. I expected bulky notes of information and half-formed thoughts in mindmaps. I love this aspect of the work because it feels like a puzzle.

How do I transform an engineer’s brief into a comprehensible guide?

How do I document an API that always changes?

Is this work purely technical or somewhat interpersonal?

Day-to-day work includes writing, but it also includes communication. I pester developers for release notes, message them with questions, and critique their docs-as-code pull requests. I’ve practiced critique as neutral. By borrowing the framework of blameless retrospectives, no person is at fault.

I struggled to find resources focused on Technical Writers reviewing others’ content. This doesn’t mean we shouldn’t improve. Relying solely on our theoretical education means relying on ingrained behaviors. We cannot allow our academic comfort to become complacency in cultural literacy.

Critiques are a collaborative discussion rather than an argument. This is normal. Even I couldn’t understand at the moment, so I had to dig deeper. I pushed in conversations to diagnose why my subject matter experts outright refused to write. I asked Engineers, Product Owners, and QA teams.

I talked with other writers. I needed to know why.

If experts don’t provide content, I can’t do my job, and users suffer.

I got my answer, but it surprised me — FEAR.

Technical Writers add a source of stress for Engineers: and that is Language Classes. Language is not only subjective, it’s also judged based on further subjective rulesets. By its nature, language can never be truly correct. Took me a while to process their behaviors, but it came down to five pointers:

— Previous bad experiences with readers

— Previous bad experiences with readers

— Limited resources and ability

— Limited resources and ability

— Conflicting priorities

— Conflicting priorities

— Fear of judgment from coworkers

— Fear of judgment from coworkers

— Lack of clear, correct content to write

— Lack of clear, correct content to write

It’s intimidating to submit content if they don’t have confidence. While search engines present lots of technical resources for non-native English speakers, very few are targeted toward writers reviewing their work. From my personal experience, I’ve found the following strategies helpful:

1. When asking about something, describe your root expectations.

2. If they aren’t comfortable writing, ask them to explain it verbally.

3. Provide templates/examples to reduce the need for formatting.

We don’t require final drafts, but that may not be clear to someone with writing anxiety. Send them the transcription so they can correct any inaccuracies and edit the way forward. This allows them to focus on the writing — not the presentation — and understand what’s needed and what’s not.

Chapter 03: The purpose of Technical Writing.

Am I unveiling the instructions so you can write perfect technical manuals?

No! Here, we’re interested in a sustainable approximation, not perfection.

Let’s start with the fundamentals of technical communication: the purpose. You’re working with a busy Product Manager who cannot waste time writing documentation. Yet all pieces of technical documentation have a straightforward purpose — help. Help whom, help how, and for what?

The answer is the 2-step approach to technical writing:

— Help users understand the context

— Help users get things done

— Help users understand the context

— Help users get things done

Step 1: Help users understand the context

Documentation is a solution to certain problems. You probably love writing above anything else, yet you get paid for solving problems — and not for writing. That’s the truth. The literature you write is a solution. This further emphasizes that the product’s users need to be introduced to that solution.

The mission of Step 1 is to explain to users why the product they bought is a solution. That‘s the context they need to have in mind when reading the documentation. The standpoint is critical. Don’t waste users’ time with information they don’t need; every word you write is costing them time.

Technical writing is neither marketing nor educating about why they should buy the product. When reading documentation, users have already purchased the product and want it to work. Remember that mastery of a topic is inversely proportional to the number of words you use to explain it.

First, master the topic, then write.

Step 2: Help users get things done

Once you have briefed how your documentation solves users’ problems, it’s all about procedures. Your audience needs help to get things done. If describing the context widely depends on the product, writing the technical instructions is always the same. An instructional document must:

— Declare in its title what users accomplish by reading

— Declare what users must know before starting

— Declare what users must have before starting

— Be a set of steps users can execute by reading them

— Give criteria to decide if the execution is successful

— Declare in its title what users accomplish by reading

— Declare what users must know before starting

— Declare what users must have before starting

— Be a set of steps users can execute by reading them

— Give criteria to decide if the execution is successful

That’s helping users to get things done. Nothing more, nothing less. Sure, there’s much more than this! The tone of voice and style, to mention a couple of examples, are additional professionalism. However, you’re a Technical Writer, not a Developer. Your goal is to deliver scannable literature!

The recipe is straightforward:

— Help users understand the context

— Help users get things done

— Help users understand the context

— Help users get things done

The recipe can be summarized with an even more concise sentence:

“Take care of your users.”

It's the same care that you must have for your users when writing.