Term

There is always a set of terms that characterizes a particular business. For the IT teams, it is crucial to get familiar with them to become equal partners for the business people. Analysts are aware of this, so most of them assemble the glossary and include it in the analysis documents. It is definitely recommended to know the terms before reading the document, but it is not good to repeat the terms in each document over and over again.

The business term is sometimes considered just a special type of business rule, which implies that the same practices should be applied:

1. They should be stored in a central, easily accessible repository
2. They should not be stored in a flat list
3. They should be referenced not duplicated

For the terms, it is even more important to be stored uniquely. Unlike business rules, which are mostly unique just within an organization, business terms might even be shared within the whole industry. This is a particularly important fact for software development companies specializing in development for a single industry. As most terms are used throughout the industry, the glossary should be unified and shared among teams working on different software for the customers within the same domain.

Despite many similarities with the general business rules, there are still some principles which apply solely to terms:

1. The term is rarely a standalone definition. Each term has synonyms, abbreviations, relationships, attributes, or states.
2. It should be easy to quickly navigate to related terms
3. Definitions should be unambiguous. Anybody reading the definition should understand it in the same way.
4. They should not include a list of systems and their descriptions. The list of systems in the organization is important, but should not be part of the glossary.

Documentation

Business terms, similarly to business rules, should be stored in a repository, not in a text format in Word or Excel. This way, they can be easily managed, referenced, and exported. However, business terms are not just "words" and their explanations. As mentioned previously, terms might be entities with attributes, states, and relationships to other entities. While the text form is sufficient for simple definitions and abbreviations, capturing the attributes and relationships is better done visually, for example, using a domain model. In Part III, we are going to demonstrate how to automatically create glossary by combining the textual descriptions with the information included in the domain models, as shown in the following picture:

The above picture illustrates that the glossary is not just a simple list of terms and abbreviations, but it is a rich representation of the business terms which could be automatically generated and could include visual elements or virtually anything which helps understand the business language.

Besides attributes and relationships, a very important aspect of the business entities is their possible states, which should be part of the documentation too. The following picture shows an example, in which the states are stored in the repository, modeled using a state machine diagram and automatically generated into the business term documentation:

Good Practices

The good practices are basically the same as for the business rules, here they are just explicitly applied to terms:

Don't Include Terms Definitions in Artifacts

Inserting terms descriptions directly into specifications leads to duplications. Store the terms in the central repository and reference them.

Don't Include Terms Definitions in Diagrams

Inserting terms descriptions directly into diagrams leads to duplications. Store the terms in the central repository and reference them.