Skip to content
Thoughtful, detailed coverage of everything Apple for 30 years
and the TidBITS Content Network for Apple professionals
8 comments

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.

Apple Style Guide Web interface

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.

Apple Style Guide ebook version

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.

Inspecting an element in Safari for the Apple Style Guide

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

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.

Subscribe today so you don’t miss any TidBITS articles!

Every week you’ll get tech tips, in-depth reviews, and insightful news analysis for discerning Apple users. For 29 years, we’ve published professional, member-supported tech journalism that makes you smarter.

Registration confirmation will be emailed to you.

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

Notable Replies

  1. I have found the use of “iDevice” to be a useful shorthand in some cases.

  2. David Pogue was always more comfortable with coining terms than we were as well. :slight_smile:

    I like to use the “right” term, even when a construction such as yours would be more convenient.

  3. I do so as well.

    It’s a good thing that I am (almost) always right. :smiley:

  4. Every publication worth reading has a style guide: a list of rules that guides the content creation process and ensures correctness and consistency.

    Thank you! My former employer had something like 30 regional offices and over 35,000 total employees. I worked in two of the regional offices, and not only was there not a standard for the entire organization, neither regional office had a style guide. Different authors in the same subsection would produce documents with different appearances! It drove me nuts. And these were for use outside the organization! (Perhaps it says more about me than the organization that I couldn’t make anyone in authority see the need for a style sheet.)

    Thanks for letting me get that off my chest, and thanks for the interesting article on styles. Speaking of which, I still miss the style sheet capability of Word 5. It seems to me that Microsoft has garbled the interface to the point where it’s almost unusable.

  5. Wow, working for an organization that large without a style guide would drive me up the wall. I’d probably make one and distribute it like samizdat, via photocopies and anonymous faxes. :slight_smile:

  6. Thank you this this! I laughed out loud at your “rabble” remark. I’ve felt uncomfortable with that lower-case “i” for a long time; it’s good to know I’m not alone!

  7. Glad you liked it. There are times when I turn to the thesaurus for just the right word.

  8. Reminds me of a few times where I used a similar technique regarding networking protocol standards.

    The official way to discuss and resolve issues is to ask questions on the appropriate IETF mailing list. But sometimes nobody bothers to answer a question, so what do you do? You can’t just wing it, because you need to interoperate with other vendors.

    In these situations, I would ask my question including a detailed description of how I think it should work, asking the local experts if there is anything incorrect in my assumption.

    If someone responds, great. Now I have an answer to my question. If not, there is now a public record if the approach being described and there being no objection. So there is at least some amount of justification when implementing the assumption.

    Of course, that only goes so far. If everybody else (or even just one the “800 lb gorilla” companies, like Cisco) is making a different assumption, then you need to go along with it, because in the world of networking, being interoperable is far more important than being “right”.

Join the discussion in the TidBITS Discourse forum

Participants