One more (maybe) post about the question of jargon in technical documents and how technical editors can tell good from bad jargon. Here are some real-world questions about jargon that came up this week in our shop and how they were resolved.
mTLS. A writer had mutual TLS in a document and then used mTLS later to refer to this. This felt like an initialism that the writer might have invented to make it easier to talk about mutual TLS. But a web search clarified that mTLS is as common initialism in other (i.e. not just our) texts.
Outcome: I added the initialism on first mention—using mutual TLS (mTLS)—and left the existing instances of mTLS.
CIAM. A similar situation. I ran into CIAM as a shortened form of customer identity and access management. I wanted to be sure that the writer wasn't just making up the initialism so I did a web search. It is used in the industry, but curiously, people have slightly different terms for C: customer, consumer, centralized.
Outcome: I made sure we wrote it out on first mention so that our reader would know which of these variants we intended.
casing. I found this text:
The email addresses johndoe@example.com and JohnDoe@example.com use different casing.
I left a query for the author and for another editor whether we were okay with using the word casing for an IT audience.
Outcome: Yes, IT people are familiar with lowercase, uppercase, camel case, etc., and they understand the word casing. (A programmer I know has a quiz that tests your knowledge of casing names.)
prefer [to]. Authors sometimes use prefer word as an imperative verb, as in Prefer using the console for this step, meaning "It's a good idea to" or "We recommend that you" (use the console). It's hard to look for examples of this usage as a verb. We had a discussion among the editors.
Outcome: We decided to recommend using We recommend instead.
[word]-aware, as in healthcare-aware. One of the editors asked whether the term healthcare-aware was okay. Another editor who works with the translators looked into it and determined that it wasn't always clear what the -aware part meant, and that different translators were handling it in different ways. A complicating factor is that -aware is in some of our product names, like Context-Aware Access and Identity-Aware Proxy.
Outcome: For the time being, we're recommending that writers not use the -aware suffix (unless it's part of a product name).
[word]-facing, as in customer-facing. This seems similar to -aware, but there are differences. For starters, a term like customer-facing is in some dictionaries. We had the same concerns as with -aware, but it looks like -facing is better established. We certainly had a lively discussion.
Outcome: None yet; to be discussed at the next style guide meeting.
quiesce. An editor raised an eyebrow about requires you to quiesce the database. Another editor said that it was common in the domain of databases, which we confirmed with a search.
Outcome: stet.
swim lane. The term swim lane was used in reference to a diagram (As shown in the swim lanes in the following diagram). I did a web search and found a Wikipedia article about this concept, suggesting that it's a term that's probably known to people who regularly see this type of diagram.
Outcome: I added a link to the Wikipedia article on first mention in case some readers don't know the term.
|
