Stop writing like an engineer

Technical writing is everywhere, regardless of your role; you don't have to be a “technical writer” to do some level of technical writing. For example, developers often need to write documentation to describe their software or how to build it.

But technical writing is a practice, and that means you can get better at writing the more you practice doing it. Ben Cotton shares this advice for developers to improve their writing style:

Put the important stuff first

I was in technical roles for first decade or so of my career. When I took a role as a technical marketing manager, my marketing VP had one regular comment on my blog posts. “Stop writing like an engineer,” he’d tell me. “Put the important part at the top. Don’t assume people will read the whole post.”

He would cut the last paragraph from my draft and put it at the top. Sometimes I’d have to tweak the wording a bit to make it flow. Otherwise, it was basically ready to go with that edit. I have some skill with writing, but I kept falling into one particular trap.

People who work in technical roles have a tendency to write linearly. They start with the problem, describe how they tried to solve it, and then talk about how well the solution worked. This is fine if the reader reads the whole post. But most people don’t do that. Especially if they’re interested in the solution, not the problem. This is especially true for marketing-type posts, but it applies in other contexts, too.

People don’t move on after the first paragraph because they hate you or you’re bad at writing. They’re busy and have a lot of other things to read. You need to tell them the important part right away. If they want to know more, they’ll read more. Putting the important part at the end doesn’t encourage them to read the whole thing; it just means they move on without reading the important part.

Avoid acronyms and initialisms

Technologists love themselves some acronyms and initialisms. (For the sake of readability, we’ll just use “acronyms” to mean both.) Maybe it’s because they tend to give things very unwieldy names. Who would want to say “hypertext transport protocol” over and over when you can say “http” instead? But acronyms can be confusing when they’re unfamiliar to your reader. Err on the side of explaining, even if you don’t think you need to.

Write it out

You’ve probably been told to expand acronyms the first time you use them. For example, you might write “hypertext transport protocol (http)”. That is good advice. Follow it. I am no longer convinced that it is sufficient advice, though.

Open source projects are full of jargon, be it unique acronyms, arbitrarily-named services, etc. If you’re lucky, new contributors are coming in. Can they understand your communication and documentation?

Until recently, I often used “FPgM” to refer to my “Fedora Program Manager” title. The role has been around for 15 years, it should be well-known, right? Then one day I was talking to a contributor who had some experience in the Fedora community. They had no idea what I said when I meant “FPgM.” Well, crap. How many other people were completely lost and never told me?

I’ve come to the view that I should avoid acronyms most of the time. What good is saving myself a few keystrokes if my reader doesn’t know what I mean?

When to use them

Acronyms aren’t always the enemy. It all depends on the context. Think about what you can reasonably assume your reader knows. Is it reasonable for them to know what it means? (Be careful. You’ll probably assume too much!) If so, then you can use it.

Sometimes it doesn’t matter if the reader knows what the acronym means. If you’re giving instructions on how to register for a website, you might tell the reader to “Go to http://example.com.” Now is not the time to explain what “http” stands for. It doesn’t matter in the context of what you’re trying to communicate. If it stood for “hotel towels: totally plush,” that wouldn’t change anything.

A combination of the previous two scenarios is acronyms that are common knowledge outside of a specific domain. Laser stopped being an acronym (“light amplification by stimulated emission of radiation”) and became a word in its own right. The same goes for “scuba.” In fact, expanding those acronyms on first use might cause confusion.

Tips for clarity

In general, you have to make a judgment call about when to use an acronym. In most cases, though, you probably don’t need to. Invest a few extra keystrokes and spell out what you’re talking about. Try one of these approaches the next time you do decide to use an acronym:

• Expand it the first time you use it
• Add a link to more information the first time you use it
• Set up an “acronym jar” that you contribute to every time you use an unfamiliar acronym

This article is adapted from Stop writing like an engineer and AIANYF: Acronyms & Initialisms Are Not Your Friends. Republished with permission from Ben Cotton.