Technical documentation that doesn’t include definitions amazes me. How can you be sure your audience is following along, especially when you’re using specific jargon? Defining terms in context works so long as you have a way for the user to come back to the context, to be reminded of the definition.

Recently I hit an issue documenting a system that used common terms differently, based on where in the system the user happened to be. Really comment terms like asset. If you’re reviewing devices, then an asset is a computer or a server, but if you’re over here, then it means a person, team, or company. Rather than providing a glossary per section, they skipped it entirely. *shakes fist*

Working in static files, it may not be possible to use on-hover functionality that displays alt text for text. How about a contextual glossary? Just a word/ abbreviation list on the page that recaps the key terms presented there. I’m thinking specifically about online user documentation I’ve been accessing lately. For a document, a section ender with that recap would be great! You can then plug all of them into a single glossary with a column for section/ context.

Then we’ll all know what we’re talking about here.