In tech writing, you have to translate jargon to a diverse audience of newbies and pros.
Storytelling Communications

Tips for Online Writing about Complex Technology


Online writing about technology poses challenges for writers, particularly when your audience includes a mix of up-to-speed professionals and clueless newbies.

To be fair, this doesn’t just apply to technology writing. Whether you’re writing about baseball, superhero comic books, or competitive square dancing, you’re often dealing with jargon and context that requires explanations. And when we as writers are familiar with something, we often lose track of the fact that it can be incomprehensible to a newcomer.

Online writing emphasizes clarity and conciseness. Whereas books or long-form articles have room for introductions, definitions, glossaries or appendices, most online readers want something they can digest easily. When writing about technology, you need to decide when something requires an in-depth explanation, or whether you can give it a cursory definition and move on.

Here are some suggestions to help your articles become clearer to the reader—and possibly easier to write—without unduly adding to your word count.

Name and Explain

The first time you mention something—particularly if it’s key to the article’s subject—give its full name, then the nickname or abbreviation you will subsequently use. This way, the unfamiliar reader doesn’t have to pause while they do a “what the heck is this” Web search. If it isn’t self-explanatory, or if it’s unclear why the term is important, include a description with just enough information to help the reader.

In most cases, expand acronyms the first time you use them, especially for names of events, organizations, and newer technologies. Examples include “role-playing game” (RPG), “bring your own device” (BYOD), and “platform as a service” (PaaS).

However, expanding acronyms word-for-word isn’t always helpful.

“The full term often has meaning only to experts,” said Mac McMarthy, a freelance writer and editor in a discussion on a technology journalists’ mailing list. “For example, ‘RAM.’ Saying ‘RAM, the computer’s working memory’ is more informative than ‘RAM, random access memory.'”

In the same discussion, Lynn Greiner, a freelance technology journalist, emphasized proper explanations for acronyms: “Many acronyms have multiple possible meanings, even just within [a] technology context. For example, will a reader interpret DOS as ‘disk operating system’ or ‘denial of service?’ Similarly, PS2 can be a gaming console or a mouse/keyboard connector.”

When you’re writing, make sure you look for possible trouble spots or areas of confusion, and explain accordingly.

Make it Easy to Track Who’s Saying What

The same applies to people you quote or mention. The first time you mention a person, give his or her full name, title, company/organization, and company URL (or, where appropriate, social media link, such as a Twitter handle). After that, you can switch to using just a last name in each new paragraph that quotes or cites the person.

Avoiding leaning on “he said” or “she said,” because it can confuse the reader if you don’t take time to re-identify the name of the speaker in a paragraph. When you’re quoting several sources, differentiate the speakers by mentioning their companies as a quick reference. For example: “said Yoyodyne’s ‘Doc’ Brown.”

Defining Newer Information

Whether through appositive or parenthetical phrases or short, separate sentences, readers will appreciate it if you make sure they know just what something is, what it does, how it fits in to the story, and why it’s important. This is particularly helpful if this is something new, not just a new version or a status update.

Another trick to describe something new and unfamiliar is by making a short comparison to something your readers should be familiar with, like saying, “RAM is like the blackboard or workbench where work-in-progress is, while storage, e.g., hard drive, solid-state drive, or USB flash drive, are the boxes and file cabinets where you put stuff away.”

Other Quick Tips

  • Lead with the main point. If you do want to start with a cute/compelling lead, keep it short.
  • Keep sentences and paragraphs short (that sound you hear is many of my editors politely coughing, perhaps even snickering).
  • Focus explanations on the here and now. Unless it’s an historical article, keep the backstory to a phrase.

If your article is still running twice or more the target length, I’ve learned that means I’m over-answering the question or the topic is too broad. Or, it means your editor should let you run long and/or split into two articles—paying you 1.5 times or twice the original price, of course (hey, it’s worth a try!).

Recommended for you