# Make specialist terminology easier to follow in an HTML report

Canonical: https://githtml.com/guides/glossaries-and-abbreviations-html
Published: 2026-09-26
Publisher: WaveTech LLC / gitHtml

Expand unfamiliar abbreviations on first meaningful use and explain specialized terms close to the argument they affect. Add a compact glossary for terms readers may revisit, using ordinary HTML text and stable links. Do not make essential definitions available only through hover tooltips, images, or external resources.

## Identify the actual knowledge gap

A document written by a specialist can assume more shared vocabulary than its audience has. Review the report for abbreviations, product-specific names, and ordinary words used with a technical meaning. Ask which terms a new reviewer needs to understand before evaluating the recommendation. Not every acronym needs a lengthy history, but important distinctions need clear definitions.

Define terms in relation to the task. A report about export reliability may need a precise explanation of artifact, dependency, and snapshot. A dictionary-style definition can be less useful than a sentence showing how the term is used here. Keep the wording consistent so readers do not have to infer whether two labels describe the same concept.

## Put help where it is usable

Explain a term on first meaningful use, then provide a glossary when repeated reference is likely. A definition list can represent term-and-description pairs without requiring a table. Give important entries stable IDs if section links would help. Keep the glossary in the same artifact when offline or low-friction reading matters.

Do not rely on a title attribute or hover tooltip as the only explanation. A touch reader may not discover it, and assistive presentation can vary. Visible text is a more dependable baseline. If an abbreviation is common within one team but ambiguous outside it, write the expanded form rather than assuming every reader shares the team's context.

## Review the report with the glossary hidden

The main argument should remain understandable without constant jumping. If nearly every sentence sends readers to the glossary, simplify the prose or add local explanations. The glossary should support reference, not compensate for writing that never introduces its concepts. Keep definitions synchronized when the document's terminology changes.

1. List unfamiliar terms before publication.
2. Expand ambiguous abbreviations in the main text.
3. Use consistent names for the same component or concept.
4. Keep essential definitions visible without hovering.
5. Check glossary links in the final export and remove unused entries.

````html
<dl>
  <dt id="term-artifact">Reading artifact</dt>
  <dd>The exported HTML file prepared for readers, separate from editable source notes.</dd>
  <dt id="term-dependency">Dependency</dt>
  <dd>A resource the document needs but does not contain itself.</dd>
</dl>
````

## Sources and further reading

- [MDN: description list element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dl)
- [W3C: understanding abbreviations](https://www.w3.org/WAI/WCAG22/Understanding/abbreviations.html)

## Related guides

- [Build a heading outline that makes a long report navigable](https://githtml.com/guides/heading-hierarchy-readable-html)
- [Use landmarks to separate navigation from the report body](https://githtml.com/guides/document-landmarks-for-html-reading)
- [Write screenshot alternatives that explain the useful information](https://githtml.com/guides/alt-text-for-document-screenshots)
- [Describe architecture diagrams as relationships, not shapes](https://githtml.com/guides/text-descriptions-for-architecture-diagrams)

Editorial approach: https://githtml.com/guides/about