My Technical Writing Soapbox

If you write on a technical topic I have one piece of advice: avoid jargon, the terms that your field uses as shorthand for specific technical things.

While explaining something from work to my wife, I once used the sentence, "The relays protect the bus from transients."

She laughed at me and had no idea what it meant. I didn't realize it when I said it, but every word of that sentence is jargon.

If you're writing for an outside audience, jargon is a barrier to understanding. You can introduce and define the terms you use but realize your audience has a limited capacity to learn them in a single sitting.

If you're writing to peers, remember that jargon is also a barrier for new folks just entering the field and you never know when you may need to sell your ideas to upper management or non-technical customers. Unintelligible jargon might impress some people but the ability to convey complex topics in simple language, much more so.

To return to my example above, what's interesting to me is how I couldn't communicate the concept in everyday terms. Regularly trying to replace jargon with simple language reveals gaps in my own understanding.

If you're curious, it means, "We use computers to sense spikes in current and voltage on the power system. These conditions can damage our equipment and the computers will disconnect the power lines to prevent that damage from happening."