Every publication that is worth reading has a style guide: a list of rules that guide the content creation process and ensure accuracy and consistency. What many do not realize is that style guides are usually used hierarchically. For TidBITS, if there is a question about how to spell, punctuate or literally a word, we first look at our own style guide. If we have not previously felt the need to establish a style government, we turn to the Apple Style Guide. For questions that Apple does not answer, at least to our satisfaction, we then go to The Chicago Manual of Style. Without guidance from any of them – or when we disagree with their suggestions – we will examine the topic on our own, make a decision and add it to the TidBITS style guide. (I do not share that document because it would be too much work to clean up for publication, given how it has evolved organically over decades of using TidBITS and taking control.)
It is worth remembering that internal style guides are just that ̵
I mention all this because Apple just updated its public style guide, which only happens once or twice a year. In addition, only recently did I learn that Apple makes the style guide available online – previously I was only aware of the eBook version you can download from Apple Books and read in the Books app.
Even though all the content was there, the Books app’s page-based browsing, slow search and hide interface make interacting with a reference book a particularly frustrating experience. Even something as simple as displaying the table of contents requires hovering over the title bar to reveal otherwise hidden controls and then clicking the table of contents button.
Apple Style Guide online
The web version of Apple Style Guide is significantly easier to use than the eBook version, and once you find an internal link to an entry, you can also link to it remotely. For example, I wrote over “download from Apple Books and read in the Books app.” Was that correct?
When I look at the listing for iBooks – the name I still think of when considering Apple’s ebook app – I see that it recommends using “Apple Books” instead. Fine, but it’s hard to write “download from Apple Books and read in Apple Books”. Fortunately, the Apple Books entry makes it clear that it’s OK to use the “Books” or “Books app.” I would do it anyway since the actual app on my drive is called “Books”, not “Apple Books”, but it’s good to see Apple confirm my instinct.
It would be useful if Apple made it easier to link to any entry in the style guide online. The only way I can see to do that in Safari is to check-click on an entry, select Inspect Item, copy the corresponding item ID from the Web Inspector and then manually embed it in the parent letter URL with a
sub query parameter.
How to link to the home screen here:
I also want to see that the search results persist, perhaps in a sidebar. When I look for help, I often perform a search and then go through each of the results. Apple Books retains the search results, so the eBook version is better for those types of search methods, although you still have to hover over the title bar to reveal controls and click the search icon each time.
A few selected style guides change
Another thing I never noticed in previous versions of the ebook style guide, perhaps because I always performed a search immediately after opening it, is that Apple includes a change to the guide section at the very beginning. It’s amazing, and it gives you an idea of how Apple’s thinking about some new technologies or reacting to world events.
In the July 2020 update, for example, 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 that Apple is writing off such racial terms.
More relevant to TidBITS are some other changes we have struggled with:
- tiltaksark and aksjeark: On a Mac, we refer to a pop-up alert, whether it’s a standalone window with an OK button or a sheet attached to a window, as a dialog. But in iOS and iPadOS, what do you call it when you press something and a popover appears with different choices? It turns out that Apple, in user material, does not want people to refer to an action sheet, which contains a list of actions, or a sharing sheet, which contains sharing destinations. But it is OK to refer to a sharing sheet when editing the content. We will probably try to avoid the terms of “action sheet” and “stock sheets” whenever possible, but since TidBITS is a relatively technical publication, we will not deviate from them completely.
- unit and product: Here is another difficulty that we encounter all the time. How do you point to something or give instructions that work on both iPhone and iPad? Before iPadOS 13, you can just say “iOS device.” In the last year, we have chosen to make it clear at the first review that something applies to both iOS and iPadOS, but in later reviews, abbreviated to only refer to iOS. In the updated device and the iOS device and the iPadOS device and product listings, Apple now (technically in the December 2019 update) says not to use “iOS device” to refer to devices that use iPadOS. However, it is 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.” Honestly, I am not happy with that solution because it is difficult to upload two (iOS and iPadOS) or three (iPhone, iPad and iPod touch) after a couple of uses in running text. We will 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 have gone with “macOS Recovery” based on Apple’s support article “About macOS Recovery”. However, a new entry in recovery mode seems to suggest that we should instead just tell people to “start up in recovery mode” (although Apple is not thrilled with startup either, and prefers startup). There are no entries for “macOS Recovery”, but for now we will stick to using that term because it is more specific and consistent with Apple’s supporting documentation.
- mode: Here is a box of worms. New in this revision is recovery mode and safe mode, where both entries note the envelope. However, the revision in February 2019 added Dark Mode, with its express capitalization, and a note that there is no comparable light mode. If the inconsistency bothers you, you are not alone, and we have suffered as well. What about mode like airplane mode, sleep mode and target disk mode? All lowercase, according to Apple. Dark Mode uses original capitals, as does Low Power Mode. But then we have Power Reserve mode, in mixed case, and Target Display Mode, which Apple uses in both lowercase and uppercase letters, but does not include in the style guide. Augh! Maybe the enabled modes are marketing features?
- Internet and web: Sometimes you just have to stick to your cannons. In the December 2019 revision, Apple came up with rants that prefer to have lowercase letters “Internet”, and added lowercase letters like “World Wide Web.” Apple is free to do as it pleases, but we strongly disagree and will continue to create both the “Internet”, in part out of respect for its power, and the “Web”, because its governing body – the World Wide Web Consortium (W3C) – activates “Web” in the style wizard. However, we may start using “site” as one word, given that W3C allows it, and there is not much reason to maintain the consistency of “FTP site” and “Gopher site” anymore. We have long gossiped about other web-related words like “webmaster” and “webcast”, but we will follow the W3C with “web page” even if Apple combines it.
If you’ve enjoyed some of the persnickety thinking that comes with making these decisions, I encourage you to browse the Apple Style Guide. It’s an informative look at the minds of at least Apple’s writers and editors who care about the clarity and consistency of the written word.