Avoiding hamburgers and kebabs
While using websites and apps, you may have seen menu items such as ≡ and ⋮. These are often referred to by people who design them as a hamburger menu (≡) and kebab menu (⋮). The names come from the visual similarity to the food and the fact that they’re usually used to open a menu of some sort.
As a vegan, I’d like to get away from metaphors based on meat. More importantly, I think these names don’t serve readers well and we should use one of the better alternatives.
What’s the problem?
The first rule in technical writing is to know your audience. (The rule is likely as important in other types of writing, but I have less experience with those.) If you’re writing for UX designers or other people familiar with such jargon, talking about hamburger and kebab menus is probably fine.
But if you’re writing for a more general audience, there’s a large chance that these terms won’t have the same meaning for them. Not everyone navigates around apps looking for food references.
Also, these terms (and similar alternatives like three dots menu) focus on only the visual aspects of the menu. So they can’t be understood by people who don’t see the visual clues. This categories includes people who:
- Are blind or visually impaired
- Don’t have the specific font installed
- Don’t load images to save data
- With different cultural contexts who have different ideas about the visual cues
If you want to help all your readers, focus on using instructions that are accessible to everyone.
What about just text?
If the product you’re documenting meets basic accessibility standards,
your buttons and other visual cues all have text alternatives.
This usually involves text that is mostly only used by screen readers,
such as the alt property on an img tag or the title element in an SVG.
These alternatives are essential for people who don’t see the visuals. Without the alternatives, such people don’t have any idea what is intended. So the first step is to make sure the product you’re documenting offers such alternatives or else push for them to be introduced.
If these alternatives do exist, your instinct might be to use just the alternatives.
For example, perhaps you have a button with an icon such as ⋮ that has an alternative text of More actions (but no regular text).
You might want to write your procedures as “Click More actions.”
The problem with this approach is that people who don’t need the alternatives often don’t see them.
So they might spend a lot of time looking in vain for the text More actions in the product.
Even if the text is a title and appears when a user hovers over the button,
they might easily miss it.
So it’s best not to rely only on the text alternatives.
Ideal solution
The ideal way to approach this issue is to have your docs match your product as closely as possible. That means if the product has a button with an icon and only alternative text (no standard text), that same button should appear in the docs. This matches the user experience in both places, making it easier to find the right action to take.
If you’re lucky enough to build your documentation site with the same technology as your product’s frontend, this can be much easier. For example, if the product includes a website built with React and you use Docusaurus to build your documentation, you can import components from your product and include them directly in the documentation files. Find a similar example in my article on documenting a design system, which did use React and a React-based site generator for the documentation (in that case Gatsby).
Alternatively, you might use a different static-site generator to build your documentation. You can create a component that replicates the functionality of the button in your product. This is the approach I took when I built an icon component for the Platform.sh docs. We used the same SVG files that were used in the product and placed them into guides on how to accomplish tasks with that product.
Reasonable compromise
Not everyone has such easily integrated products and docs. Some don’t have any development resources to devote to getting such a solution to work.
In cases where you can’t get the ideal to work, it makes a lot of sense to find another solution that does work with your publishing flow. Just make sure that it includes options that are clear both for people who only see the visual cue and people who never see the visual cue.
As an example, you might be able to include an inline screenshot of the button
and use it next to the alternative text for the button.
So in Markdown, you might use something like Click  More actions,
with an HTML equivalent of Click <img src="path/to/image" alt="" /> More actions.
Keep in mind that repeating text doesn’t make the result more accessible.
This means that if you are including the alternative text in the documentation itself,
you don’t need to include the same text as alternative text for the image of the button.
For more information,
see the Web AIM guide to alternative text with examples when empty alt attributes are recommended.
Terminological footnote
In discussion on this issue in the Write the Docs Slack community,
I often see people using the terms button and icon interchangeably.
As a technical writer, especially one with a background working with a design team,
this mixing seems unfortunate.
I would suggest the terms should be used for different things:
- If you can interact with an element, it is a button.
- If the element is just a visual, it is an icon.
Note that an icon can be part of a button (the visual cue part),
but you wouldn’t say Click the icon, only Click the button.
(Although with the style guides I am most used to,
you would leave out button entirely and just use the name of the specific button.)
I think this distinction is useful and should be maintained. But I understand, as with many such aspects of language (such as jealousy and envy), it’s not a distinction everyone follows naturally and it’s not a battle often worth fighting. But if you are writing your own words, it can help to stick to it.