The First Three Rules for Technical Writing

Small businesses and start-ups (maybe ones like yours!) can be chaotic.

You’re focused on your product, on your growth, and on user retention. And you wear a lot of hats. You might be a co-founder chairing a panel at a Marketing event one day… and a plumber fixing a leaky sink in the break room kitchen the next day.

Oh, did I mention you really need to do something about your product documentation? Like, actual user guides and full technical content for your products? Yeah, your product managers don’t have the time or expertise to manage your help and support content and your engineers are too far from your customers to connect the dots between the product, the use case, and the value prop.

Sigh… one more thing for someone to learn. It’s either that or you have to dig around for budget to bring someone on full-time or maybe to contract a freelancer.

Now, depending on your businesses size and the complexity of your products, that might be your best move. But, if you aren’t quite there yet, you’re in luck: with degree courses, certificate programs, and online content, it’s easier than ever to get a handle on skills and tactical tips and tricks.

But where should you start?

Three Rules: Technical Writing for Beginners

This post won’t go into the various courses, programs, and more that you can find out in the wild (check out the Society for Technical Communications for that… or, you know, YouTube). We won’t even spend too much time on tactical tips.

Instead, this post will cover the three rules that can help guide your approach as you learn how to become a technical writer for your business.

Chances are you know a little about communicating already—you’ve got this far already! And these three areas of focus won’t shock you. But they will help you focus the skills you have already to help you be there for your customers when they need help.

Taken together, focusing on these three rules can help provide your customer-users with content that is easy to understand, familiar and approachable, and considerate of their experience using your products.

Let’s get into it!

Clarity

Clarity is the rule that comes before anything else.

If you don’t communicate with clarity, you’re not communicating at all.

In his essay Politics and the English Language, George Orwell (yes, that George Orwell) laid out the following rules for writing with clarity. He probably didn’t know it at the time, but these are also useful guidelines for great, clear technical writing:

1.Never use a metaphor, simile or other figure of speech which you are used to seeing in print.

2. Never use a long word where a short one will do.

3. If it is possible to cut a word out, always cut it out.

4. Never use the passive where you can use the active.

5. Never use a foreign phrase, a scientific word or a jargon word if you can think of an everyday English equivalent.

6. Break any of these rules sooner than say anything outright barbarous.

One thing you might realize as you undertake writing with these rules in mind is how common it is to do these things when communicating about products—especially technology:

• We break #2 when we use longer, less common words to sound smarter (cringe) and less repetitive.

• We break #4 when we want to hide or cover-up the fact that we are responsible for introducing a limitation in a product that we don’t want to admit we are responsible for.

• We break #5 when we use jargon to try to make our technology sound like our products are “techno-magical”.

Simply put, keeping clarity at the forefront as you write about your product keep you customers from getting more confused during the moments they are already seeking out help with your products.

Consistency

Clarity might come first, but you can enable clarity by maintaining consistent language and usage across all your content.

Your product (hopefully 😅) has its own set of design patterns. In the same way that UX, engineering, and design teams reuse those patterns across your products, you need to have a consistent approach to how you write about everything related to your products.

Why does this matter? A few reasons:

• User comfort. When you use the same names for elements in a product, and use the same language for behaviors and concepts, you teach users how to use the product and what to expect from it.

• User confusion. When we use different names for concepts in the platform, or use different language for behaviors and concepts, we introduce the opportunity for confusion.

Of course, the more content you have—and the more people you have contributing to it—the more difficult it can be to maintain consistency. Some ways of helping your team include:

• Avoiding inconsistency by creating a style guide to establish consistent expectations for your documentation

• Choosing a shared “fall-back” style guide for usage your business doesn’t have special rules for. I like using the Microsoft Manual of Style for tech products but it’s common to see AP or Chicago used as well.

• If you’re in a pinch, just check to see whether there are already patterns in your current content that you can mimic.

A quick note: your business might already have a brand guide that guides your voice and tone, and which suggests a particular general style guide for your content marketing and copywriting. Consider whether those (usually Marketing-specific) choices make sense for technical writing. Do they make for clear, concise technical copy? If not, go your own way.

When it comes to your technical writing, your customers come first.

Empathy

Speaking of your customers…

Your customers encounter your help content in context with everything else going on in their lives. Strive to help solve their problems and answer their questions efficiently and thoughtfully.

This rule should be the easiest one, but sometimes it’s the most difficult. Remember to center your writing on your audience: it’s their experience, their goals, and their perspective we need to write toward. When you’re writing about how to use your products, be sure it respects that perspective.

Put another way: write to serve your customers—not your ego.

Remember that users don’t want to just know how to use a feature in your product, they need to know how to solve their problems with your product. Your writing should aim to define and then solve those problems. In some respects, your product is the last piece of the puzzle—it’s the way you connect the user to the solution.

As you write about your products, you have to sell its use and value to your audience. Don’t assume they know why it matters for them to use a feature or what value will be in it for them. Every time you have a chance to communicate your product’s value, you should look at it as an opportunity to win hearts and minds.

Putting It Together

You don’t have to be an expert technical writer to start thinking like one. You probably already have some content that you create for your customer-users, so applying the three rules as you optimize that content can help make it more valuable.

If you’re not sure whether you’re ready to learn another skill set, you can always hire an expert to point you in the right direction.

But first, that break room kitchen sink is leaking again. Better get on that!