Terms are the foundation of communication. Terms appear in documentation, and if you are lucky, they are explained in a glossary. If you are extremely lucky, your company maintains a term dictionary that lets define words and abbreviatons online, discuss them, link them, and adapt them over time, representing some kind of common sense for the company's business. Reality is, most of us are neither lucky nor extremely lucky:-(
We find out how important term definitions are when we have to maintain source code using business terms that were not clearly defined at the time of writing. Developers invent their own terms and acronyms when they were not accurately introduced into the business. These inventions tend to be purely technical, in a way that you can not read the business from such source code any more. Events and processing mixed up with business events and workflow processes.
People prefer jargon to simple language. Maybe they want to protect knowledge by using words that is known to a limited number of persons only. Some say that acronyms are the only way to have a short description for an abundance of semantic. Some say that it is the only way to bind a very general word to their according context. No science without scientific language. Whatever the motivation for business language is, we need to map it to normal language somewhere.
The simplest way for binding a word to a meaning is to have a table with two columns, left the term, right the definition (description, explanation):
| Term | Definition |
|---|---|
| Jargon | The specialized terminology associated with a particular area of activity. |
| .... | .... |
Mind that you should keep the terms in alfabetical sort order, else people won't use the glossary.
Adding terms with the same meaning in a "Synonyms" column is useful:
| Term | Synonyms | Definition |
|---|---|---|
| Description | Explanation | The pattern of narrative development that aims to make vivid a place, object, character, or group. |
The "Term" column should contain just one single word or word group, the "Synonyms" column can contain several comma-separated terms.
Abbreviations (acronyms) for business terms are frequently used:
| Term | Synonyms | Abbreviations | Definition |
|---|---|---|---|
| Definition | Description, Explanation | DEF | A statement about the meaning of a term (word, phrase, or set of symbols). |
"Term" should be a sortable column. If "Synonyms" and "Abbreviations" contain just one word, this would be useful for them too.
As we have so many languages on this planet, it is nice to provide a commonly known one. Here is a German glossary with English term translation:
| Begriff | Synonyme | Abkürzung | Definition | English |
|---|---|---|---|---|
| Abkürzung | Akronym | Abk. | Verkürzte Darstellungsform eines Wortes oder einer Wortgruppe. | Abbreviation |
To keep a glossary simple we need to know its context or targeted audience. Synonyms may be interesting for business experts only, abbreviations just for developers. Glossaries that also contain a "Context" column may become too big.
It makes sense to put abbreviations into their own table, and keep them apart from terms. Mostly they are clearly distinguishable from normal words, and they are more often reason for a search than words.
Mind that abbreviations often are used like normal words, think of "CV" (curriculum vitae).
Nobody wants to read glossaries. You go there when you need to. Thus we should link terms to the glossary wherever they occur. In case your documentation system supports hyperlinks this may be easy. Some Wikis even support automatic term linking.
Another way is a cross-reference index that provides an alfabetical list of terms with the page numbers where they occur. Well known for printed books.
Words live when used by people. You can keep them alive by relating them to some meaning or context well-known to all involved persons. Glossaries are the simplest way to share knowledge. What about term-oriented software development?
ɔ⃝ Fritz Ritzberger, 2020-11-14