THE GITHTML FIELD GUIDE
Review an AI-generated project glossary for overloaded terms
An AI-generated glossary is useful only when its definitions match how the project uses each term. Verify terms against interfaces, domain rules, and maintainer explanations. Distinguish overloaded meanings and avoid treating a class name as a complete definition. Include a concrete example and a non-example when the boundary is easy to misunderstand.
Identify terms that cause real confusion
Do not ask for every noun in the repository. Select words that affect decisions, such as account, workspace, job, request, or session. An illustrative export system might use job for a queued unit of work and request for the user's original intent; collapsing them into synonyms would obscure retries and ownership. Diátaxis separates reference from explanation, which helps frame a glossary as a concise lookup resource. Link longer conceptual discussions rather than turning every entry into an architecture essay. Note the domain and version when a term has changed meaning.
Verify a definition through usage
For each candidate term, inspect relevant schemas, function boundaries, and user-facing text. A name such as active may mean currently enabled, recently used, or not deleted; the definition needs evidence of the actual rule. Ask the responsible maintainer when usage is inconsistent. An illustrative entry could define export attempt as one processing execution for an export request, with a retry creating another attempt. Include that only if the project's model supports it. Label fictional examples clearly and avoid importing terminology from another product just because it sounds familiar.
- Definition: state the meaning within this project and scope.
- Evidence: link the rule or interface that establishes that meaning.
- Boundary: add an example and distinguish the nearest confusing term.
Keep the glossary small and connected
Remove entries that merely restate ordinary words without helping the reader. Add aliases where historical or user-facing terminology differs, but explain which name is preferred and why. Review the glossary after a domain-model change and search for inconsistent usage in the associated guide. In HTML, meaningful term headings allow quick navigation on a phone; short definitions are easier to scan than a giant grid. The glossary is authored and reviewed outside gitHtml, then read as committed content rather than inferred dynamically from repository names.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.