Homepage
Login
New Post
Profile
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?
(3)More posts by @Hamaas631
3 Comments
Sorted by latest first Latest Oldest Best
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."
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.
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.
Terms of Use Privacy policy Contact About Cancellation policy © selfpublishingguru.com2024 All Rights reserved.