Maintaining a project glossary as the shared vocabulary

Goal

One place where every term the project uses in code, interface, documentation and conversation has one meaning, so that "account", "customer" and "tenant" cannot silently denote the same thing in three places and different things in a fourth.

Prerequisites

A location that every document can link to (a GLOSSARY.md in the repository or one wiki page), an owner who merges changes, and agreement that the glossary term is the term used in identifiers and user-facing text. Fowler (cited) describes the domain-driven-design practice of building up a common, rigorous language between developers and users, based on the model in the software; the glossary is that language written down.

Steps

1. Seed the list from the nouns in the data model, the resources in the API, and every term that has caused a misunderstanding in a review or an incident.
2. Use one entry shape: term; one-sentence definition; what it is not (near-synonyms and the difference); an example; where it appears (table, field, endpoint, screen); status (preferred, deprecated with the replacement, avoid).
3. Choose exactly one preferred term per concept. List the rejected synonyms as entries that point to the preferred term, so a search for the wrong word still lands.
4. Expand abbreviations at first use in every document and in the entry itself. RFC 7322 (cited) says abbreviations should be expanded in document titles and on first use; Google's style guide (cited) asks that necessary jargon be defined on first use or linked to a trusted definition.
5. Link the first occurrence of a term in a document to its entry instead of redefining it inline; inline definitions drift.
6. When a concept is renamed, change the glossary in the same commit as the code and the documentation, mark the old term deprecated with the date, and keep it for a release cycle so that old logs and tickets remain readable.
7. Review the glossary when the data model changes and at each release; delete entries nobody links to.

Expected result

New contributors and agents can resolve any term in one hop; reviewers can reject a change that introduces a second name for an existing concept by pointing at the entry.

Limits and test basis

A glossary does not settle disagreements about the domain; it records the outcome. Terms that users say and terms the code uses may legitimately differ, and the entry should then state both. The procedure is proposed; no measurement of reduced misunderstanding is claimed.

Scope by bounded context

One meaning per term holds within a bounded context, not across a whole organisation. When a project spans several domain modules or services, keep one glossary per context, each with its own owner, and apply the entry shape and the one-preferred-term rule inside it. Add a short cross-context table that lists the words used with different meanings on each side (account in billing versus identity) and how each side's concept maps to the other's; that table is the context map in prose. Do not rename a concept in one context to resolve a collision with another; record the collision instead. A project with a single model is a single context and needs one glossary.