If you write technical documentation for or blog about Apple products, you’ve probably pondered phrasing, capitalization, etc.. If you’re not familiar with it already, Apple publishes and updates a style guide that’s complete and useful for any kind of Apple-related writing. I’ve broken plenty of rules over my career, but I’ve been internalizing as many of these as I can, especially for software documentation.
You can download the full PDF of the style guide from Apple, and there’s a web-based HTML version available now, too. Here are a few highlights that are the most relevant to me:
Actions
Do you “type” a key? “Hit” a shortcut? The rule is that you “press” keys and shortcuts, “type” strings, and “tap” anything on a multi-touch screen. And when talking about on-screen buttons, you “click” (or “tap” in the case of touch interface). “Press” is only used to refer to hardware or mechanical buttons (such as the Power button).
Key combinations
Modifier keys have always been confusing to me, but there is a clearly defined style that makes a lot of sense.
First of all, you always capitalize modifiers like Shift and Option. You hyphenate combinations, e.g. Control-Option-A. Two-word keys like “Up Arrow” maintain the space between the words. If the key name is hyphenated itself, use an en-dash when writing the combination.
Sequential keystrokes
When the shortcut being listed is a sequence, use a space between the characters. This differs from manpage-style documentation, where it’s not uncommon to see a comma instead. Apple suggests that you “be sure to explain this convention on first use,” writing out the process after listing the sequence the first time it comes up.
Modifier combination ordering
Here’s the most commonly ignored rule regarding key combinations (and one that I’ve had to go through Marked 2 documentation and update myself a few times): there’s a specific order in which modifier keys should be listed when combined:
- Control
- Option
- Shift
- Command
So “Shift-Option-C” is wrong; it should be “Option-Shift-C.” The latter sounds right when you read it, but it’s not always obvious when writing.
Function/Escape
I’ll just quote this one because it’s very straightforward:
Spell out the key names Escape and Function (the Fn key on portable computers and wireless keyboards) when you introduce them. In subsequent references, it’s OK to abbreviate them as Esc and Fn.
Graphical representation
When you’re showing graphical representations (images showing keys in physical form) of key combinations, the rules change. In this case you use a plus sign (+) between the keys instead of the hyphen.
If you blog about Apple products, or write documentation for Apple hardware or software, I highly recommend reviewing the style guide. It’s well-indexed for quick reference, so go grab the PDF and keep it handy.
I added a quick cheat sheet for these particular points to Cheaters, but you can also add a link to a local copy of the PDF in your Cheaters index and have the full version available.
