Post History

Source: https://writers.stackexchange.com/q/33553
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

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](https://en.wikipedia.org/wiki/Representational_state_transfer) 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?

Original score: 6