I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 35 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

Blog Search

(Supports AND)


Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.


You cannot persuade someone to consider an idea by debating them into submission.

Reg Braithwaite


<June 2024>



Contact Me

Email me

Blog Statistics

First entry - 6/27/2003
Most recent entry - 6/2/2024

Posts - 2654
Comments - 2677
Hits - 2,672,104

Entries/day - 0.35
Comments/entry - 1.01
Hits/day - 349

Updated every 30 minutes. Last: 10:27 PM Pacific

  08:15 AM

In a webinar last week on technical editing, I talked about how technical editors need to be mindful of terminology: they need to be aware of the terms that are common in a domain but also be on the lookout for "jargon." There was a follow-up question about how you know which is which, and I don't feel like I did a good job explaining. So here's a second attempt. :)

What's "good" jargon?

Part of the issue is that the word jargon has two meanings. In the "good" sense, jargon is the specialized terminology of a domain. This can be technical terms themselves, words like the following:

  • macula and percutaneous transluminal coronary angioplasty (medicine)
  • commoditization and Gini coefficient (economics)
  • affinitization and instantiation (computer programming)
  • em dash and down style (editing)

These terms have specific, technical meanings to practitioners in the field, and they're going to appear in specialized literature for the field. People who don't know the field quite likely won't know the terms.

Another kind of good jargon comprises terms that are used as a kind of shorthand in the field. They're not necessarily technical terms, but they're words or expressions that everyone in the field knows. Some examples might be well-known abbreviations or shortenings. A few examples:

  • Foley for Foley catheter in medicine
  • mono for monoaural in sound engineering
  • fintech in the investment world
  • sync and DevOps in IT (also, IT in IT, haha)

I say that these terms are good jargon because they work in the service of clear and concise communication. When I'm talking to a group of American copyeditors, I can say things like "AP and Chicago disagree in some of their guidance about hyphenization and passive,"[1] and it's hard to imagine that the audience would not understand this sentence, even though there are abbreviations (AP), shortenings (Chicago, passive) and technical terms (hyphenization, passive).


This of course brings up the question of audience and context. For that sentence about editing, I was explicit that I was talking to American copyeditors. The sentence probably wouldn't be entirely understandable to my wife, let's say (who's in healthcare), and I wouldn't assume that British copyeditors (subeditors) necessarily know the terms AP and Chicago. (They might, but it doesn't seem like a safe assumption.)

A responsibility for the technical editor during developmental editing is to work with the author to determine who the audience is and what they do (or don't) know

As I had noted during the webinar, a responsibility for the technical editor during developmental editing is to work with the author to determine who the audience is and what they do (or don't) know. An article in a specialized journal is going to have a different audience than a post on Medium, and the editor has to take that into account when gauging whether good jargon is appropriate. But if the author and editor agree that the audience has the background to understand this good jargon, there's no reason not to use it.

This can be fuzzy. It's not like there's a single canonical reader for every piece of writing. It's fair for an editor to make queries to the author: Will the reader understand Foley? Do we need to define affinitization? Are you sure that readers know what AP means? Do IT people really say sync for "synchronization"?[2]

Editors lean toward spelling out and defining. This tendency is generally good; the editor is advocating for the set of readers (perhaps small but non-zero) for whom a term is unfamiliar. In many cases, the editor and author might agree to define on first mention, or use the full form, or at least link to an explanation.

But it can be overdone. Spelling out or defining terms that every reader knows can not only be annoying ("Why are you telling me this?"), it can subtly affect the reader's perception of the piece ("Do you think I'm a noob?"). I sure hope never to encounter a text that talks about "amplitude modulation/frequency modulation (AM/FM)" radios. In technical articles for computer programmers, I would strike well-meaning attempts to spell out HTML or API, because if the reader doesn't know these terms, the rest of the article is not going to very comprehensible either.

What's "bad" jargon?

So that's good jargon. What makes for "bad" jargon? One kind of bad jargon is slang. For example, programmers talk about cruft to refer to code that's no longer useful but that hasn't been removed and is still junking up the system. Anyone who's been in the programming world probably knows this term, but it's probably not appropriate in documentation.

Another example of bad jargon is domain-specific terms for a non-domain audience. The issue here is context: words that are perfectly fine in one context and for one audience are problematic for a different context and different audience. An example that I used in the webinar is that terms that might be fine for an auto repair manual (like "the throttle") might not be acceptable in that same auto's owner's manual ("the gas pedal").

So-called business-speak (aka corporate jargon) often combines slang and domain terminology. If you read about "having a one-off face-to-face to iterate on the cadence of deliverables" or "the candidate has been actioned and will be onboarded next week," you might throw up your hands at his hopeless jumble of jargon. But it's important to keep in mind that these sentences are (usually) perfectly understandable to people who write these things and to their intended audience. In other words, context is important. Where this becomes a problem is if the text is aimed at someone outside the "speech community" that understands it, like a press release or an all-hands email.

Finally, there are invented terms. For example, I've often seen an author invent an abbreviation or initialism for a gnarly multi-word term because they don't want to have to repeat it. Officially, we frown on this practice, because it introduces unfamiliar terms that the reader has to then keep track of ("What does that mean again?"), not to mention that it might cause problems for translators later.

How can you tell good from bad jargon?

A big question is how a technical editor can tell the good jargon from the bad jargon. As you can probably guess by now, I'm not going to propose any sort of absolute measure.

Back to first principles: who's the audience and what do (don't) they know? I can't emphasize enough how critical this is to sorting out the question of what constitutes acceptable jargon.

But suppose that while technical-editing a piece, you've run up against a term that feels like jargon and you're wondering whether you should allow it. Here's what I would do:

  • Look at the style guide. I don't mean AP or Chicago here; I mean the usage guide you use for the domain. For example, imagine you're reading draft programming documentation and you keep running across foo and bar. Is this okay? If you're at Microsoft, probably yes. If you're reading a document that use the verb to trial, is that okay? If the document is about medical trials, there's a good chance that it is. Obviously, this means you have to be familiar with the usage guide or guides for the domain you're editing in.

    Corollary: If you don't already have a style sheet, create one to track the decisions you've made about these terms.
  • Research. Do a web search for the term. If you get results, see if they seem to be in the same domain as what you're editing. If it looks like other writers in the field use the term, it might be okay. But be sensitive to whether you're seeing the term in official documentation or in less formal text, like blog entries.

  • Ask other editors. If you have colleagues, discuss it with them. They might have seen the term before and know whether it's acceptable. If you don't have colleagues nearby, put the query out on editor-facing[3] social media, targeting other editors in your field if possible. Include as much context as you can, because, as I keep saying, context is important.

  • Ask the author. Tell the author that a term seems jargon-y to you and you'd like their input it. (I would be careful to phrase the query to make it clear that it seems jargon-y to you, not that it necessarily is jargon.) The author might point you to other examples[4] or to information that can help you both make a decision about keeping or replacing the term.

  • Ask the translators. If the material is going to be translated and if you have access to the people who manage translations, you might be able to ask them. Translators often have databases of terminology; for example, they might reassure you that they can handle foo or onboarding just fine.

In a sense, I'm suggesting that you put the brakes on your hard-won editorial sensibilities. More on that in a second.

Update: I added a post with some real-world examples that illustrate jargon that we encountered and how we resolved questions about it.

But that's a terrible term!

One of the things I noted during the webinar is that it's not the editor's job to pass judgment on terminology. If people in a domain have settled on terms like operationalize or onboarding or upsert, it's not our job as editors to come in later and say "You shouldn't use that term because it's ugly" (or "it doesn't make sense to me" or "I don't like it"). Our concern is not with our personal reaction to a term, but whether it's being used correctly for the audience. As Judith Tarutz says, “The jargon and conventions of technology are sometimes incompatible with or different from the rules of English.”

Our concern is not with our personal reaction to a term, but whether it's being used correctly for the audience

This isn't to say that you have to love every word you encounter. We editors wouldn't be text-sensitive readers if we didn't have aesthetic preferences for language. But there are times when our personal preferences are not the factor by which we judge usage.[5] You might never develop a fondness for the word onboarding or actioned, but that's what folks in HR say, and our concern is that they're using that word correctly and consistently for their audience for this document.

However, …

However, there is an exception. If a term is potentially offensive or triggering, or if it perpetuates harmful stereotypes, then it is our job as editors to bring this to a writer's attention. An example from the world of software is the term whitelist. This was coined to contrast with blacklist. In IT, whitelisting means to explicitly allow something or someone—for example, an email spam filter allows you to create a whitelist of senders whose message you'll accept.

Over the years, we've asked writers to move away from terms that assign good/bad values to black and white. So instead of saying "Add users to a whitelist," we suggest "Add users to an allowlist" or something similar.

This is an ongoing effort, because whitelist is widely used in software. Still, by changing this usage one instance at a time, we're hoping to move writers toward less charged language.

There are other, similar terms that we try to move writers away from. In a couple of instances, this has resulted in some pretty lively discussions. Authors who defend these terms make much the same argument that I was making earlier about good jargon—namely, that when you're writing for a known audience, you should use the vocabulary that that audience knows. Generally, our compromise is to include a term to establish a mapping, something like "Add users to an allowlist (whitelist)." This also helps if the user performs a search for the term. But after that first mention, we don't use the term again.

Authors are usually satisfied with this compromise. But not always. And in those cases, we have to rely on our author-editor relationship to see what we can do.

It's not easy

The original question—how can you tell good jargon from bad jargon?—doesn't have an easy answer. I hope I've provided some context and some useful suggestions. I would love to hear how other tech editors approach this question.

Since we're talking about jargon, let me finish by including links to some funny lists of domain-specific jargon:

and lest we forget …

[1] I don't actually know this is true, but bear with me.

[2] It's always a fun discussion to ponder the past tense form of "to sync."

[3] "editor-facing": jargon?

[4] Embarrassingly, more than once an author has pointed to a similar usage in our own doc set.

[5] I suppose I should add that I feel that any argument to the effect of "But it's degrading English!" is irrelevant, unless someone can show data showing how and how much a usage degrades the language.


[1] |