Maintain a Glossary

To enforce a common understanding of the domain, a glossary should define the terms important for the project. This also supports the ubiquitous language and makes sure nobody is left behind.

Domain
Documentation
Type
Collaboration
Principles
Principle of least Astonishment, DRY Principle

Teams and also single authors need to use terms in the documentation correctly.

Writing demands to use the same wording for the same concepts. It is also necessary to define the terms of the domain so that they are commonly understood. How can this be achieved?

Structure

Glossaries contain the definition or description of a term. This not only includes the spelling, but also the semantics. An entry of a glossary also allows to add metadata and references to related terms and other information about the term.

A glossary does not need to be created in advance. It can be created on-the-fly. Whenever authors use a term that is part of the domain, the term is added to the glossary. If the term already exists the authors can make sure that it is used correctly and probably add additional information to the term's page in the glossary. If there are any problems encountered, the term should be discussed within the team.

A glossary may also help to create an ubiquitous language as demanded by the Domain Driven Design approach.

Advantages

  • A glossary ensures a common understanding of the terms.
  • A domain may be analyzed by the team based on the teams.
  • A glossary makes the domain knowledge explicit.
  • A glossary may be used by style guides to ensure a common wording.
  • A glossary supports
    • Single Sourcing: Each term is defined on a single page
    • Single Point of Access: additional information about the term is found on this page

Disadvantages

  • Creating a glossary requires resources.
  • Defining or even only describing a term is not easy.

Related Practices

The following practices are related to this practice.

Employ a Style Guide
All publishing organizations define a style guide for their published information. Such a guide supports teams to write in a similar tone, making it easier for readers to digest the information.
Keep a Journal
In order to take personal notes on one's own work and to reflect upon what has to be done or has been done, keep a journal. The information in the journal should be shareable at least with all team members.
Single Sourcing
Reduce redundancy by having one source of truth for each information. This way the written information is more easily reusable in other documents and - which is even more important - it is referenceable. Single sourcing demands automation.

Resources

For more information regarding this practice please refer to:

Glossary
To work with a domain everybody needs to use the terms unerringly. Create a glossary to create a common understanding of your domains.
Glossary Item
Glossary items are part of the domain glossary for the project. Glossaries support the team to use terms of the domain consistently in conversations and documentation.
Index Entries Table Macro
Renders a table of index entries.
Index Card Macro
Renders transcluded content fetched from documents of a result set.
Short Name
A shorter or abbreviated name of the document.