Gary M. is a 5-Star Writer Access writer.
We computer techies know how to talk to other techies. We have our own language. It’s precise, it’s to the point, and it shows no mercy to those who don’t have the necessary background. But what do we do when we’re not writing for each other? We need to reach the managers who make important tech decisions. How do we write so that we’ll get their interest and let them understand the issues? How do we help them make informed decisions about purchases and policies?
In the article “Avoid These Technical Writing Mistakes,” Robert W. Bly, the director of the Center for Technical Communication, put it bluntly:
The average engineer in industry cannot write clear, lucid prose. He or she may know the basics — sentence structure, grammar, punctuation, and exposition. However, most engineers have just a few poor stylistic habits that mar their technical writing, making it dull and difficult to read.
Bly was writing for industrial engineers, but we have the same issues, though we don’t like to admit it. His admonition applies whether we’re writing about firewalls in a building or firewalls in a network.
Explaining without condescending
The most important point in writing about tech is this: Don’t talk down. Everyone hates being talked down to, but it’s especially true of managers. The difference between explaining and condescending may seem subtle, but there are techniques to keep readers from feeling insulted.
Pexels.com/Ruslan Burlaka
Get the reader on your side. We’re all experts here (notice how I just followed my own advice), but we need to address our readers as equals whom we’re helping. Managers are reading the article in order to learn something. You’re helping them to get something done, not giving them instructions to follow passively.
Give the benefit of the doubt. Don’t think of the reader as Dilbert’s tech-ignorant boss. You can start with something like “Let’s review the topic,” or “Since not all of you may be familiar with this, let me briefly explain.” That suggests that the reader may understand, but you have to explain for the sake of those who don’t.
Give readers credit for knowing their job. We like acknowledgement of our expertise; so do managers. Make it clear that while you’re explaining the technology, you know that they understand their business.
Avoid jargon for jargon’s sake. Use technical terms where they’re necessary, and define them if they aren’t common among non-techies, but resist the temptation to show off with terminology. As Bly puts it, “Write in plain, ordinary English and your readers will love you for it.”
How much detail?
The question of terminology is part of the bigger question of how much detail to present. Provide too little and you haven’t conveyed your point. Provide too much and you lose the reader. Hitting the right point depends on factors such as the type of publication and its expected audience. A quick 300-word piece can’t do more than identify an issue and say why it’s important. A longer piece in a popular magazine can say more, but it can’t require sustained concentration. A publication or blog that focuses on solving problems requires more detail.
Research is important — not just of the topic, but the publication. Hit the level of technical complexity which the readers expect, and you’re on target. Go too light or too heavy, and the reader will skip to something else.
Keeping it clear
Writing on technical subjects is complicated enough under the best of circumstances. We have to be extra careful that our style lets the information shine through. An article on the IEEE website, “Write Clearly and Concisely,” offers some excellent tips on how to do this. A lot of it is standard advice that’s still worth heeding: Use simple but specific words, eliminate unnecessary ones, prefer the active voice, avoid multiple negatives and noun strings, etc.
The “known-new contract” is a less familiar idea. This says that the known information in a sentence should precede the new information. For example: “Spam filters may block ordinary phishing attempts [known information] but fail to catch highly targeted ‘spearphishing’ [new information].”
Respect the reader
Thinking of the reader as a “pointy-haired boss” won’t work. Think of the writer as an equal, as someone who’s as capable as you are but has different skills. Assume that a manager who reads your writing can understand it, as long as you do your job of making it clear. Then write so that it is!
Read back your own writing and think, “If I were a manager and not a tech specialist, how would I react to this? Would I understand it? Would I appreciate it? Would I want to take action on it?” Make changes where necessary so that your target audience will get it. If you can do that, you’ll deliver the kind of article that works for them. [Tweet This]
Gary M is a software engineer as well as an experienced author, with three books to his credit. His background allows him to cover a broad range of tech topics, including WordPress, Web design, computer security, and cloud computing.
See for yourself why thousands of companies use WriterAccess to get great content. Open your free account today.
