Bridging the gap between colloquial usage and technical meaning of terms
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?
This post was sourced from https://writers.stackexchange.com/q/33553. It is licensed under CC BY-SA 3.0.
3 answers
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.
This post was sourced from https://writers.stackexchange.com/a/33556. It is licensed under CC BY-SA 3.0.
0 comment threads
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
This post was sourced from https://writers.stackexchange.com/a/33554. It is licensed under CC BY-SA 3.0.
0 comment threads
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.
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.
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.
0 comment threads
0 comment threads