Good Terms

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.

Glossaries

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

Context and Audience

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).

How to Write Definitions

1. Don't use the left-side term in the right-side definition, this would be self-explanatory!


2. Don't use left-side terms in definitions at all. Explaining "definition" by "description" and "description" by "definition" leaves the reader alone. Use plain language, understandable by the majority of people.


3. Add delimitations of the term.


4. Give examples, they convey certainty about correct understanding.


5. Add pronounciation, because people will talk about the terms, and they should understand each other. For example the computer tool curl is actually pronounced "kurl", pronouncing "see-url" may lead to misunderstandings nowadays ...


6. In an abbreviation glossary, always give the long form of the acronym, because people would remember it better when seeing the parts it was created from (WYSIWYG = What-You-See-Is-What-You-Get).

Who Reads Glossaries

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.

Conclusion

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?