Today I was working with Allison (a content strategist I often work with) and how to represent some keyboard shortcuts came up.
Telling people which keys to press is the sort of thing that is easy to do when sitting next to someone but is more challenging in a written form.
Specifically we came across some situations where a command you wanted to use a lowercase key to access a shortcut, we wrote this down on paper as:
y ('y' is lowercase) to copy a line
I thought the intent would be clearer if we used monospaced typewriter text, the sort that people use to render code snippets, so I suggested this:
y to copy a line
While I thought this was a bit better it does come from working in a demographic that sees such monospaced text as verbatim commands, I was asked if there was something similar that didn't have as much of an assumption behind it. My proposed change was higher-context than I first realized (meaning that successfully interpreting this needed to draw upon more context than I had hoped) and Allison astutely pointed this out and that there could be issues with this depending on my audience (these are the sorts of subtle points that make working with a skilled content strategist worth it)
I remembered that there's these keyboard icon symbols, but for the life of me I couldn't remember what exactly they were.
It also is really hard to search for since the search terms are highly saturated with completely irrelevant results. To add extra difficulty the modern search engine trend of "trying to guess what I was really searching for" made it even harder to find. Thankfully I remembered where I saw these last so I made a trip over to my browsing history to find the Super User post I'd remembered seeing these at last.
In this post it shows you that cmd + tab will cycle through windows. But that cmd + ` will cycle through windows only of the same active application. This is an incredibly handy keyboard shortcut that's worth remembering, so useful that I'll do some quick and dirty spaced repetition and use this immediately again for my example,
By using the developer dev tools I could see what I needed and it's the
People have even various tools to make this HTML easier to create such as markdown-it-kdb
So now let's say we wanted to describe how to cycle through application windows on Linux or Windows, we can do this like so:
<p> On Linux or Windows we can cycle through application windows by pressing <kbd> alt </kbd> + <kbd> tab </kbd>. We can cycle through windows of the same app by using <kbd> alt </kbd> + <kbd> ` </kbd> <p>
Now to make this work we actually have to have some CSS that will nicely render the keyboard keys since the default styling is just monospaced font (other browsers may do something differently).
So we have to put together some custom CSS too, thankfully auth0 has already put this together under a MIT licence here: https://github.com/auth0/kbd
Coming back to the original example:
y to copy a line
Seems to avoid any ambiguity and hopefully more clearly conveys the intent including to non-technical users.