Improving acronym usability in the handbook
Problem to solve
As per onboarding we are discouraged to use acronyms unless it is beneficial:
While we avoid acronyms typically so that Everyone Can Contribute, there are times that the easiest way to achieve mutually exclusive, ubiquitous language (referred to as MECEFU terms) is through acronyms. When that is the case, there should be a glossary in the handbook for that function defining the terms, and we should avoid using acronyms in written form without explaining them at least once in the same document.
My main issue with the current usage of acronyms in the handbook is that it's definition isn't always readily available at the point where I am reading it. Sometimes it might be defined higher up on the page or only on the glossary which means I have to leave the context that I am in to make sense of it.
Intended users
Employees and prospective employees.
Further details
Use case: user reading the handbook Benefits: ensure the user can get the definition of an unfamiliar acronym without needing to lose the context of where they are reading
Proposal
While avoiding acronyms is a good objective it isn't feasible to get away from it totally and as such I would like to propose we improve the usability of acronyms by making the definition available right there in the context that it is used.
Feature description:
- Show a tooltip when the user hovers their mouse over the acronym (desktop) or taps on the acronym (mobile).
- Decorate acronyms visually to indicate that they are interactive, for example:
- Underline acronyms with a dashed line
- Show acronyms in a different color
- Change the mouse pointer into a help symbol on hover
How we implement this
I suggest that the annotation of acronyms be done automatically through a build job that can scan for and wrap acronyms with the relevant markup.
Acronyms could be defined in a YAML file containing the acronym and its definition.
Defining acronyms in a separate file has the added benefit of being able to add a validation step that could reject a Merge Request if it introduces a new acronym that is not defined yet.
What does success look like, and how can we measure that?
Acceptance criteria: any acronym added to the handbook is automatically annotated during the build process so that a reader of the handbook can get the definition of the acronym through interacting with the acronym.
Links / references
https://alistapart.com/article/hattrick/
https://www.nngroup.com/articles/tooltip-guidelines/
cc @gl-website