Bridging the gap between colloquial usage and technical meaning of terms

Question

Frequently, at least in the software world, it seems that terms get assigned a meaning over time that is more general than the original definition. REST is a good example of this. While REST refers to a specific way to architect web services, it has become associated with popular styles of making simple web service that often don't fit those guidelines. Even among software developers there is often confusion about the meaning or generality of the term. Many are either not aware of the formal definition or intentional ignore it because the misuse has become so pervasive.

All of that is to say that even when writing technical documentation for consumption by technical people, there could be confusion about what the term itself means (despite it actually having a formal definition). However, I tend to be fairly pedantic about these kinds of things and want to be clear that in my documentation I mean the formal definition. At the same time, I don't want to come across as confrontational. Simply linking to a good definition might get ignored by those that think they know the term, while calling of out the differences between common usage and formal usage might take up too much space and be seen as patronizing to some.

How can I ensure that my documentation is clear and well-defined without belaboring the differences between the common and formal uses of a key term?

Answer 1

This issue falls under the "know your audience" rule of (technical) communication. If you are clear on the distinction between canonical definitions and colloquial usage in your product, and if you know something about your readers' points of view, you are able to clarify wherever the distinction is useful or necessary.

A glossary is a great tool/resource. I'm hesitant to recommend only a glossary because when people see a term they (think they) know, they're not going to check the glossary unless -- maybe -- they really get confused. They don't know what they don't know.

In the main content, something like a parenthetical or sidebar tip with a link to the glossary might be useful in a particular context. For example: "Note: REST commonly refers to foo. In this documentation, REST includes any bar. See the glossary for a full explanation."

Answer 2

People choose words to make distinctions. Sometimes the distinctions they are trying to make are fine-grained and sometimes they are not. In many cases, the people making the coarse-grained distinctions are not even aware that the fine-grained distinctions exist. People tend to choose the most familiar word that makes the distinction they are interested in at the time. This is a reasonable communication strategy because the most familiar word communicates best.

There are two downsides to this habit, though.

1. It can be confusing or upsetting to people who are aware of the more fine-grained distinction and are used to using the word in question to make the more fine-grained distinction.

2. It can cause confusion in discussions where the more fine-grained distinction is being made, and one of the parties is not aware of the fine-grained meaning of the word.

A classic case of this is the work "Kleenex". As a brand name, it denotes a particular brand of facial tissue. But the word Kleenex is the most well known word in this space and is therefore commonly used to mean any facial tissue. If you asked someone for a Kleenex and they refused on the ground that the only facial tissue they had was Scotties brand, you would not be impressed. For present purposes, the fine-grained distinction between Kleenex and Scotties facial tissues is not of interest to you.

This happens to all sorts of words. Lots of people use "Microsoft" to mean Microsoft Word. Lots of people use REST to mean a general class of web protocols of which actual REST is just one example.

One of the hardest communication problems is to make someone understand and accept a distinction more fine-grained than the one they are used to making. Not only is this conceptually difficult, people also tend to think you are being pedantic about your words rather than making a real world distinction that really matters in the current circumstances.

You are not going to solve this class of communication problem simply by standing your ground on the more precise meaning of the word. Most people are not even going to notice you are doing it. They will hear the word in the sense they are used to using it.

Instead, you are going to have to close in on the distinction you are trying to make by way of stories and examples (like my Kleenex example above). Once you have got the distinction itself across, you can reintroduce the term in its more refined sense and people will accept and use it in that sense if you have convinced them of the importance of the distinction you are asking them to accept. But you have to justify the distinction before you can get the reader to accept the redefinition of the term, regardless of the word's history or original meaning.

Answer 3

I'd recommend using a glossary.

You can use the glossary to clearly define each term that you apply in a certain way in your document. Almost every specialisation has its own set of terms, and an unambiguous meaning is the basis of many in-depth explanations.

The great advantage is that a glossary is distinct from the flow of the document. People familiar with your text and/or the field will skip and save the time. Newbies will find the basics neatly piled in a stack where they can find it easily and refer to at need while reading.

Answer 4

I see a certain amount of benefit in pedantry - you are signaling to a knowledgeable in group, that your documentation, and by inference your product, follows expected standards. Whenever I notice a deviation from the strict definition I wonder where else is this product going to let me down.

However, as pointed out by bookeater - use of a glossary helps to define terminology "for the rest of us" - and therefore doesn't exclude the novice from using the document, it also does not impede the flow of the document itself.

Furthermore, you can keep to the use of proper definitions where possible (e.g RESTful), and create new terms such as REST-like as common usage diverges from the original meaning.

Answer 5

In language, when a mistake becomes common enough, it's standard usage.

One way to check whether the original meaning of a word has evolved beyond your preferred usage is to check a dictionary or other relevant reference.

Representational state transfer