Updated Apple Style Guide Available on the Web and in Apple Books

Every publication worth reading has a style guide: a list of rules that guides the content creation process and ensures correctness and consistency. What many people don’t realize is that style guides are usually applied hierarchically. For TidBITS, if a question arises about how to spell, punctuate, or capitalize a word, we look first to our in-house style guide. If we haven’t previously felt the need to establish a style ruling, we turn next to the Apple Style Guide. For questions that Apple doesn’t answer, at least to our satisfaction, we then go to The Chicago Manual of Style. With no guidance from either of those—or when we disagree with their suggestions—we’ll research the topic on our own, come up with a ruling, and add it to the TidBITS style guide. (I’m not sharing that document because it would be too much work to clean it up for publication, given how it has evolved organically over decades of TidBITS and Take Control usage.)

It’s worth remembering that internal style guides are just that—internal guidance—and no one outside the organization needs to follow any dictum in a style guide. For instance, Apple doesn’t generally use articles with trademarked product names, which leads to corporate-sounding sentences like “iPhone supports the most popular email standards.” The rest of us would throw a “The” at the start of that sentence to make it sound less stilted.

I mention all this because Apple just updated its public style guide, something that happens only once or twice per year. Plus, only recently did I learn that Apple makes its style guide available on the Web—previously, I had been aware only of the ebook version that you could download from Apple Books and read in the Books app.

Although all the content was there, the Books app’s page-based browsing, slow searching, and hide-and-seek interface make it a particularly frustrating experience for interacting with a reference book. Even something as simple as viewing the table of contents requires mousing over the title bar to reveal otherwise-hidden controls and then clicking the Table of Contents button.

The Apple Style Guide on the Web

The Web version of the Apple Style Guide is distinctly easier to use than the ebook version, and when you can find an internal link to an entry, you can also link to it externally. For instance, I wrote above “download from Apple Books and read in the Books app.” Was that right?

When I look at the entry for iBooks—the name I still think of when I consider Apple’s ebook app—I see that it recommends using “Apple Books” instead. Fine, but writing “download from Apple Books and read in Apple Books” is awkward. Luckily, the Apple Books entry clarifies that it’s OK to use “Books” or “the Books app.” I would have done that anyway since the actual app on my drive is called “Books,” not “Apple Books,” but it’s good to see Apple confirming my instinct.

It would be helpful if Apple made it easier to link to any entry in its style guide on the Web. The only way I can see to do that in Safari is to Control-click an entry, choose Inspect Element, copy the associated element ID from the Web Inspector, and then manually build it into the URL for the parent letter with a sub query parameter.

That’s how I’m linking to Home screen here:

• URL for the letter H: https://help.apple.com/applestyleguide/#/apsg9dac5903
• Element ID for Home screen: apd3e3bb1ae1c194
• Full URL to Home screen: https://help.apple.com/applestyleguide/#/apsg9dac5903?sub=apd3e3bb1ae1c194

I’d also like to see search results persist, perhaps in a sidebar. When I’m looking for help, I often perform a search and then want to go through each of the results. Apple Books does retain search results, so the ebook version is better for that sort of search approach, although you still have to mouse over the title bar to reveal controls and click the search icon each time.

A Few Select Style Guide Changes

Another thing I never noticed in previous versions of the ebook style guide, perhaps because I was always performing a search immediately after opening it, is that Apple includes a Changes to the Guide section at the very beginning. It’s fabulous, and it gives you an idea of how Apple thinks about some new technologies or is reacting to world events.

For instance, in the July 2020 update, we learn that Apple now capitalizes Black when referring to ethnicity or cultural identity and recommends alternatives to blacklist/whitelist and master/slave. It’s nice to see Apple deprecating such racially charged terms.

More relevant to TidBITS are some other changes with which we’ve struggled:

• action sheet and share sheet: On the Mac, we refer to a pop-up alert, whether a free-standing window with an OK button or a sheet attached to a window, as a dialog. But in iOS and iPadOS, when you tap something and a popover appears with various choices, what do you call it? It turns out that, in user materials, Apple doesn’t want people to refer to an action sheet, which provides a list of actions, or a share sheet, which contains sharing destinations. But it’s OK to refer to a share sheet when you’re editing its contents. We’ll probably try to avoid the “action sheet” and “share sheet” terms when possible, but since TidBITS is a relatively technical publication, we’re not going to shy away from them entirely.
• device and product: Here’s another tricky one that we run into all the time. How do you refer to something or give instructions that work on both the iPhone and the iPad? Before iPadOS 13, you could just say “iOS device.” In the past year, we’ve opted to clarify at the first mention that something applies to both iOS and iPadOS, but in subsequent mentions, shorten to just refer to iOS. In the updated device and iOS device and iPadOS device and product entries, Apple now (technically, in the December 2019 update) says not to use “iOS device” to refer to devices that use iPadOS. However, it’s acceptable to say, “Learn how to back up your iOS or iPadOS device” and even better would be to say, “Learn how to back up your iPhone, iPad, and iPod touch.” Frankly, I’m unhappy with that solution because listing either two (iOS and iPadOS) or three (iPhone, iPad, and iPod touch) items gets awkward after a couple of usages in running text. We’ll continue to ponder and deal with it on a case-by-case basis.
• recovery mode: When you hold down Command-R while your Mac starts up, you end up in what? We’ve been going with “macOS Recovery” based on Apple’s “About macOS Recovery” support article. However, a new recovery mode entry in the style guide seems to suggest that we should instead just be telling people “to boot into recovery mode” (although Apple isn’t excited about boot either, preferring startup). There is no entry for “macOS Recovery,” but for the time being, we’re going to stick with using that term because it’s more specific and matches Apple’s support documentation.
• mode: Here’s a can of worms. New in this revision are recovery mode and safe mode, both of whose entries note their casing. However, the February 2019 revision added Dark Mode, with its express capitalization, and a note that there is no comparable Light Mode. If the inconsistency perturbs you, you’re not alone, and we’ve suffered from it too. What about modes like airplane mode, sleep mode, and target disk mode? All lowercase, according to Apple. Dark Mode uses initial capitals, as does Low Power Mode. But then we have Power Reserve mode, in mixed case, and Target Display Mode, which Apple uses both in lowercase and with capitals but doesn’t include in the style guide. Augh! Perhaps the capitalized modes are marketing features?
• internet and web: Sometimes, you just have to stick to your guns. In its December 2019 revision, Apple fell in with the rabble that prefers to lowercase “Internet,” adding it to the lowercase short form of “World Wide Web.” Apple is free to do what it wants, but we disagree vehemently and will continue to uppercase both “Internet,” partly out of respect for its power, and “Web,” because its governing body—the World Wide Web Consortium (W3C)—capitalizes “Web” in its style guide. However, we may start using “website” as one word, given that the W3C allows it and there isn’t much reason to maintain consistency with “FTP site” and “Gopher site” anymore. We’ve long lowercased other Web-related words like “webmaster” and “webcast,” but we’ll follow the W3C with “Web page” even though Apple combines it.

If you’ve enjoyed some of the persnickety thinking that goes into making these decisions, I encourage you to browse through the Apple Style Guide. It’s an informative look inside the heads of at least the authors and editors at Apple who care about clarity and consistency in the written word.