nico.fyi

Learning Microcopy from Apple Style Guide

October 20, 2019 in articles

Few days ago, someone tweeted about this online document from Apple called Apple Style Guide. It’s the first time I heard about it and I’m pretty sure I’m not the only one. After skimming the document, I found many interesting tidbits about microcopy and copywriting. So this weekend, I decided to read everything.

For native English speakers, the content of this Apple Style Guide might not be so interesting, but for those who use English as second language, this document could help you make your apps or products better, especially if your apps are using English.

If you don’t have the time to read everything, I curated the document in this article. Most of the things mentioned in the document is to avoid confusion and ambiguity for the users of Apple apps. I picked some parts that I found interesting, or even new to me.

activate, deactivate

Avoid; instead, use turn on, turn off.

alert

In user materials, you can use alert sound or alert message to describe generic alerts. Avoid error message except in developer materials.

The computer plays a sound (called the alert sound) when it needs your attention.

An alert message appears if a problem occurs during the installation.

In specific situations, however, avoid the word alert if you can simply describe what happens.

A message appears when the installation is finished.

allow

Avoid using allow when you can restructure a sentence to make the reader the subject.

Avoid: FileMaker Pro allows you to create a database.

Preferable: You can create a database with FileMaker Pro.

alternate, alternative

Use alternate to mean every other or occurring or proceeding by turn. Use alternative to mean allowing two or more choices.

You can shade alternate rows of a table.

When traffic is heavy, Apple Maps provides alternative routes.

and/or

Rewrite to avoid this construction.

Correct: document and app icons

Avoid: document and/or app icons

program

In general, use program only to refer to software that doesn’t have a graphical user interface.

The launchd program consolidates all system startup activities into a single program.

appear

Use appear, not display, to refer to items becoming visible on the screen.

Correct: The setup assistant appears.

Incorrect: The setup assistant is displayed.

Incorrect: The setup assistant displays.

assure

Don’t use when you mean ensure. Assure means to state positively, so as to remove doubt.

Assure customers that you’ll resolve the issue.

auto (prefix)

Close up except before a vowel.

autoconfiguration, autoplay, autosave, autosensing, autosync

auto-answer, auto-update

back end, back-end

back end for noun. back-end for adjective.

backlight, backlit

backlight for noun, backlit for adjective.

badge

Don’t use badge as a verb or badged as an adjective. An item has a badge, or a badge appears on an item.

based

Use a hyphen in compound adjectives that include based when they precede a noun.

application-based services, Windows-based computer

Use an en dash (Option-Hyphen) if based follows a term with two or more words.

Windows XP–based computer

Don’t use a hyphen or an en dash in predicate adjectives that include based.

Each track in a sequence is assigned an index value that is zero based.

blank character

Don’t use; use space character.

Bluetooth

Don’t use Bluetooth as a noun.

Correct: If your computer didn’t come with an internal Bluetooth module, you can have one installed by an Apple Authorized Service Provider.

Correct: Your computer can connect to and transfer information to devices that use Bluetooth wireless technology.

Incorrect: Your computer can connect to devices that use Bluetooth.

Don’t use a hyphen with Bluetooth.

Correct: Bluetooth enabled device

Incorrect: Bluetooth-enabled device

braces

Use braces, not curly brackets, to describe these symbols: { }.

When you need to distinguish between the opening and closing braces, use left brace and right brace.

brackets

Use brackets, not square brackets, to describe these symbols: [ ]. Don’t use brackets when you mean angle brackets (< >).

When you need to distinguish between the opening and closing brackets, use left bracket and right bracket.

browser, Internet browser, web browser

Use lowercase for browser when referring to an app used to gain access to the web and other Internet and intranet services.

bug

Avoid; use problem, condition, issue, or situation instead.

built-in (adj.), built in (pred. adj.), built into (pred. adj.)

In headings that use title-style capitalization, don’t capitalize in (exception to the rule of capitalizing the second word of a hyphenated compound).

Built-in Apps on Your MacBook [heading]

You can use the built-in microphone or an external microphone.

Mac Pro has 512 GB of flash storage built in.

Two-factor authentication is built into iOS 9 and later.

Button names

In general, write the names of buttons exactly as they appear onscreen. If the button’s name uses sentence-style capitalization, enclose the name in quotation marks. If the button’s name uses title-style capitalization, don’t enclose the name in quotation marks, even if one of the words is in lowercase.

Click Cancel.

Click the “Position on screen” button.

Tap Add to Favorites.

If a button name uses all capital letters or all lowercase letters, use title-style capitalization when writing the button name.

If an element in the user interface looks like a button (is enclosed in a rectangular border) and acts like a button (causes something to happen when clicked), always call it a button (don’t call it an icon).

If an element in the user interface looks like an icon (is a graphic but isn’t enclosed in a rectangular border) but acts like a button (causes something to happen when clicked), call it a button.

canceled (v.), canceling (v.), cancellation (n.)

Use one l for the verb cancel—for example canceled, canceling. Use two l’s for the noun cancellation.

can, might, may

Use can to express the capacity to do something; use might or may to suggest the possibility of doing something; use may to express permission.

You can log in to your account from another computer.

You might be able to connect to the Internet at a nearby hotspot.

You may borrow my iPod if you return it tomorrow.

When used to express possibility, might typically suggests lower probability than may.

If the issue persists, you may need to restart your computer or you might need to restore software.

capability

If possible, avoid capability when you discuss features of software or hardware. Reword in terms of what the user can do with the feature.

Correct: With Photos, you can create slideshows.

Incorrect: Photos has the capability to create slideshows.

cell phone, cellular phone

Don’t use; use mobile phone.

check

Don’t use when you mean the action of selecting a checkbox. Use select instead.

checkbox

A checkbox can be selected or unselected. Avoid saying checked and unchecked.

If “Allow repeated calls” is unselected, multiple calls from the same person do not go through.

If “Allow repeated calls” isn’t selected, …

choose

Use choose, not select, for menu items. In general, the user selects something (such as a file or disk icon, an email message, or a section of text) and then chooses a command to act on the selection.

Choose View > Sort By > Date.

Select the text to copy, and then choose Edit > Copy.

Click the pop-up menu, and then choose High Priority.

Control-click the TextEdit icon, and then choose Make Alias.

click

Use to describe the act of selecting something or initiating an action by positioning the pointer over an onscreen element and briefly pressing and releasing the mouse or trackpad.

To open Mail, click the Mail icon in the Dock.

Click a disk icon to select it, and then choose File > Make Alias.

Don’t use click on. Don’t say click the mouse or click the trackpad; instead, use press and release.

Press the mouse, drag to enclose the area you want to select, and then release.

colons

Follow these guidelines for using colons:

  • In running text: Capitalize the first word after the colon if the word begins a complete sentence (exception to The Chicago Manual of Style).

There are two ways to raise or lower text in relation to adjacent text: You can make characters superscript or subscript, or you can adjust the baseline shift.

Ordinary video clips and image files have three channels of color information: red, green, and blue.

  • In headings: If you use a colon in a heading, capitalize the first word after the colon, regardless of its part of speech.

Setting up: A beginner’s guide

  • With lists: Precede every list with a colon, whether the sentence before the colon is a complete thought or a partial thought (exception to The Chicago Manual of Style).

command

A command is in a menu, not on a menu; a menu contains commands. Users choose commands; they don’t select commands.

command names

Use title-style capitalization for command names; don’t capitalize command.

the Find command

the Make Alias command

  • Commands used as ordinary verbs: Don’t capitalize a command name when you use the name as a normal English verb.

Correct: Cut and paste the selected text.

Incorrect: Cut and Paste the selected text.

  • Ellipsis: Some menu commands use an ellipsis to indicate that further action will be required. Don’t include the ellipsis when you refer to the command name in text or text headings.

Correct: Choose File > Print, and then enter the number of copies.

Incorrect: Choose File > Print…, and then enter the number of copies.

commas

Use a serial comma before and or or in a list of three or more items.

Correct: You can ask Siri to place phone calls, send text messages, send reminders, and more.

Incorrect: You can ask Siri to place phone calls, send text messages, send reminders and more.

crash

Don’t use; use quits unexpectedly, doesn’t respond, or stops responding. If you must use this word, put it in quotation marks and reassure the reader that the term crash doesn’t imply damage to hardware or software.

dash (em)

Use the em dash (—) to set off a word or phrase that interrupts or changes the direction of a sentence or to set off a lengthy list that would otherwise make the syntax of a sentence confusing. Don’t overuse em dashes. If the text being set off doesn’t come at the end of the sentence, use an em dash both before it and after it.

See all your schedules—work, school, and social life—in one app.

To generate an em dash in a word-processing app, press Option-Shift-Hyphen. Close up the em dash with the word before it and the word after it.

dash (en)

The en dash (–) is shorter than an em dash and longer than a hyphen. Use the en dash as follows:

  • Numbers in a range: Use an en dash between numbers that represent the endpoints of a continuous range.

bits 3–17, 2003–2005

  • Compound adjectives: Use an en dash between the elements of a compound adjective when one of those elements is itself two words.

desktop interface–specific instructions

Grammy Award–winning producer

ex–Sun Studio tour guide

  • Minus sign: Use an en dash as a minus sign (except in code font, where you use a hyphen).

–1, –65,535

To generate an en dash in a word-processing app, press Option-Hyphen. Close up the en dash with the word (or number) before it and the word (or number) after it.

data

Singular or plural, depending on the context. When used as a collective noun, data takes a singular verb. When the meaning isn’t collective, use a plural verb. In user materials, avoid in favor of information if information makes sense in the context.

Collective and thus singular: Data is stored in a FileMaker Pro database.

Not collective and thus plural: Selected data are transferred immediately.

dimensions

In general, use by, not x, to show dimensions.

3.2 by 6.0 by 11.4 in. (8.1 by 15.2 by 28.9 cm)

8.5 by 11 inches, 8.5-by-11-inch paper

4 by 6 inches, 4-by-6-inch photo [acceptable: 4-by-6 photo, 4 x 6 photo]

If you use x instead of by, use the x consistently throughout a document.

disable (v.), disabled (adj.)

In user materials, avoid disable when you can use turn off or deselect. Don’t use disabled when you mean unavailable (when you refer to menu items).

Correct: Make sure virus-protection software is turned off and your computer isn’t set to go to sleep.

Avoid: Make sure virus-protection software and system sleep are disabled.

In developer materials, it’s OK to use enabled and disabled when you describe buttons, menu items, and the like.

Don’t use disabled as an adjective to refer to people. If it’s relevant to refer to people having a disability, refer to the people first and the disability second.

Correct: Apple provides innovative solutions for students with disabilities.

Incorrect: Apple provides innovative solutions for disabled students.

double click (n.), double-click (v.), double-clicking (n., v.)

Small children may have trouble with a double click.

Adults can double-click without difficulty.

You do this by double-clicking the icon.

double tap (n.), double-tap (v.), double-tapping (n., v.)

A simple double tap lets you zoom in.

Double-tap the photo to zoom in or out.

You can zoom in by double-tapping.

earlier, later

Use to refer to versions of software; don’t use lower and higher or newer and older.

You can make and receive phone calls on your iPad or iPod touch (iOS 12 or later), Apple Watch (watchOS 4 or later), or Mac (OS X 10.11 or later).

To use Group FaceTime, you must have macOS 10.14.1 or later installed.

To take an ECG, you must have Apple Watch Series 4 with watchOS 5.1.2 or later.

e.g.

Don’t use; use for example or such as.

email (n., v., adj.)

One word.

Send an email to your manager.

Your manager wants you to email her.

You can set up email filters.

When referring to more than one email, use email if you’re using the word in a collective sense; use emails to refer to a specific group or type of emails.

You can filter incoming email.

Here are tips for how to avoid phishing emails.

Flag important emails to make them easier to find later.

You can use messages to refer to email if the context makes it clear you’re talking about email, not text messages.

enable (v.), enabled (adj.)

Avoid in user materials when you mean turn on. Turn on implies initiating an action or starting a process immediately; enable implies doing a task that makes subsequent actions possible.

Correct: Turn on Windows file sharing.

Incorrect: Enable Windows file sharing.

Don’t use enabled when you mean selected (for example, when you refer to radio buttons or checkboxes) or available (when you refer to commands or buttons that are sometimes dimmed, but not in this case).

Correct: Make sure the Magnification checkbox is selected in Dock preferences.

Incorrect: Make sure the Magnification option is enabled in Dock preferences.

Correct: The Copy command isn’t available because no text is selected.

Incorrect: The Copy command isn’t enabled because no text is selected.

Don’t use enable when you mean give the ability to. You can usually rewrite a sentence to avoid it.

Correct: With iMovie, you can view, edit, and share movie projects.

Incorrect: iMovie enables you to view, edit, and share movie projects.

It’s OK to use enable to describe a task that makes other actions possible.

To use this website, you must enable cookies.

In developer materials, it’s OK to use enabled and disabled when you describe buttons, menu items, and the like.

enter

Use enter, not type, to describe inputting text-based information by typing, copying and pasting, dragging, or some other method. Use type to describe pressing or tapping keys to produce characters on the screen. Use press, not type, to refer to pressing keys on the keyboard.

Enter your account information and tap Save.

The intelligent keyboard may suggest corrections as you type.

Press the Return key.

fair language

Avoid cultural biases and stereotypes, which may offend some users of Apple products. Be aware of the variety of people who are potential Apple customers, and write consciously to include them.

Names: In examples, include a variety of ethnicities, and use both female and male given names.

Given name examples: Anton, Avram, Gabrielle, Jim, Luisa, Mei, Sanjiv, Yoshiko

Family name examples: Contreras, Johnson, Kawabata, Meyer, Scharanski, Stern, Wong

Situations: Portray both women and men in a variety of occupations and situations, not just stereotypical ones.

Pronouns: Avoid using gender-specific pronouns generically. When referring to an individual of an unspecified gender, don’t use he, she, he or she, or he/she. First try to rewrite the sentence to avoid the need for a singular pronoun.

Avoid: The student imports his GarageBand composition into iTunes.

Avoid: Each student imports his or her GarageBand composition into iTunes.

Preferable: The students import their GarageBand compositions into iTunes.

When revising a sentence isn’t possible or the result is awkward, it’s OK to use they as a singular and gender-neutral pronoun.

FAQ

Abbreviation for frequently asked questions. FAQ is singular; use the article an. Use FAQs to refer to more than one set of frequently asked questions. Use title-style capitalization if the full term precedes a noun: the Frequently Asked Questions document.

front end (n.), front-end (adj.)

Note hyphenation of adjective.

functionality

In user materials, avoid if you can use a word such as features instead.

Avoid: Some functionality is not available in certain regions.

Preferable: Some features are not available in certain regions.

future tense

Whenever possible, use present, not future, tense. Don’t switch unnecessarily from present to future tense when present tense is sufficient to express a sequence of steps or events.

  • Conditional constructions: Use present tense for conditional constructions such as the following:

Correct: If the noWait parameter is true, play from the disk stops immediately, and program control returns to the caller.

Incorrect: If the noWait parameter is true, play from the disk will stop immediately, and program control will return to the caller.

  • Future events: Future tense is sometimes appropriate—for example, when a product described isn’t yet available.

Apple will give users a peek at the new app by releasing a public beta.

Next year students at Clareton High School will use EPUB textbooks in their math classes.

gray

Not grey.

grayed

Don’t use; use dimmed.

grayscale (n., adj.)

One word.

hang

Don’t use as a description of the computer’s behavior in response to a system error; use a phrase such as not responding.

Correct: If the computer doesn’t respond to input from the mouse, trackpad, or keyboard, a system error may have occurred.

Incorrect: If the computer hangs, a system error may have occurred.

highlight (v.)

Don’t use when you mean select.

Correct: Select the text you want to change.

Incorrect: Highlight the text you want to change.

Don’t use as an intransitive verb.

Correct: As you type in the search field, matching icons are highlighted in the window below.

Incorrect: As you type in the search field, matching icons highlight in the window below.

humor

Humor can enhance documentation by adding to a reader’s enjoyment and by helping to lighten the tone. Humor usually works best in examples, where it’s less likely to distract the reader.

Be careful that your humor is in good taste—one reader’s joke can be another reader’s insult—and keep in mind that humor may not translate well in localized text.

if necessary

Avoid in user materials. Instead, describe the circumstance in which the action would be necessary.

Correct: If file sharing isn’t on, turn it on.

Incorrect: If necessary, turn on file sharing.

Correct: If the file size is larger than the maximum your mail app allows, compress the file.

Incorrect: If necessary, compress the file.

if, whether

Use if to indicate a condition. Use whether when two outcomes are possible.

If you can mentally introduce the words or not in a clause, use whether rather than if.

Correct: When you start editing a locked file, the app asks whether you want to unlock it.

Incorrect: When you start editing a locked file, the app asks if you want to unlock it.

indeterminate progress bar

In developer materials, the progress bar that has a spinning striped cylinder. In user materials, use progress indicator and describe what it looks like.

Developer materials: Use an indeterminate progress bar when the duration of a process can’t be determined.

User materials: A progress indicator (a spinning striped cylinder) lets you know that a process is taking place.

into, in to

Use in to when in is part of the verb. Use into to imply motion to the inside of something.

Correct: Log in to the computer.

Incorrect: Log into the computer.

Correct: Insert the CD into the optical drive.

iPhone

When writing the names of iPhone XR, iPhone XS, and iPhone XS Max, use small caps for the R and S if your tools let you. If your tools don’t offer small caps, use uppercase R and S. Don’t use lowercase.

Preferable: iPhone XR, iPhone XS, iPhone XS Max

Acceptable (in case of tools limitations): iPhone XR, iPhone XS, iPhone XS Max

Incorrect: iPhone Xr, iPhone Xs, iPhone Xs Max

The letter X in the model name is pronounced “ten” (for example, “iPhone ten-ess”).

latest

Don’t use to refer to a specific software update. Instead, use only the version number (or a date, in technical support documents), or use or later to indicate a range of updates. It’s OK to use latest if you’re generally instructing users to keep their software up to date.

Correct: To use this feature, you must have iTunes 12 or later installed.

Correct: For the best results, make sure you’re using the latest version of macOS.

let

Avoid using let when you can restructure the sentence to make the reader the subject.

Acceptable: The Sort command lets you sort items in your document.

Preferable: You use the Sort command to sort items in your document.

Or: You sort items in your document with the Sort command.

like, love

Users can like or love an item. Items can have likes, but not loves; instead, refer to loved items as items you’ve loved or loved items. Users can dislike a liked or loved item. Don’t capitalize like or love unless you’re referring to a button in the user interface (for example, the Loved button).

Telling Apple Music what you love and dislike improves future recommendations.

In News, when you like a topic or channel, related stories appear more often in For You.

In iTunes, create a Smart Playlist of your loved songs and albums.

To avoid ambiguity, you can also say mark an item as liked, an item is marked as loved, or similar.

The album subscriber marked the photo of the Grand Canyon as liked.

link (n.)

A user clicks a link to go to another page or to perform an action. Avoid using follow a link; use click a link instead.

Correct: Click a link on the homepage to go to another page.

Incorrect: Follow the link to the page of your choice.

link (v.)

OK to use when you describe the act of creating a link on a webpage, but don’t use link to describe connecting to a webpage.

Correct: When creating a webpage, be sure to link to other interesting webpages.

Incorrect: Click the map to link to other pages on the site.

localize (v.)

Takes the preposition for, not to.

Correct: Whether you localize your app for the French language or for French Canada, make sure you test its interface.

Incorrect: Whether you localize your app to the French language or to French Canada, make sure you test its interface.

login (n., adj.), log in (v.)

Use to refer to the procedure for starting use of a Mac system account. Use log in to, not log into.

Correct: You must log in as an administrator.

Correct: If you turn on automatic login for yourself, your account opens when the computer starts up.

Incorrect: You must log into the computer.

Users log in to a file server (not log on to); users log out of a file server (not log off, log off of, or log out from).

Correct: You must log out of the server.

Incorrect: You must log out from the server.

Incorrect: You must log off the server.

Use login window to refer to the window that appears when a new user logs in to macOS.

mode

In user materials, avoid mode when you refer to software features.

Correct: When you’re using the paintbrush…

Incorrect: When you’re in paintbrush mode…

Correct: Use full-screen view to play your presentation.

Incorrect: Use full-screen mode to play your presentation.

It’s OK to use mode in user materials when you’re discussing hardware—for example, to refer to a state that a computer or iOS device is in (such as camera mode, sleep mode, safe mode, or target disk mode). However, don’t overuse mode; it can often be omitted with no change in meaning.

native

In user materials, avoid using native to describe apps; instead, describe the apps as being designed to work with specific hardware or software.

For best performance, use an app designed for use on Intel-based Mac computers.

new

In most documents, avoid describing a product or feature as new because the text will quickly become out of date. When appropriate, state the version of software in which a feature was introduced.

Correct: Auto Unlock, introduced with macOS Sierra 10.12…

Incorrect: The new Auto Unlock feature…

number sign

Use to describe this character: #. Don’t use pound sign or number symbol. Avoid using the number sign to specify an item in a numbered series.

You can frequently omit number or the number sign from a sentence and still make the meaning clear.

See document 58677 for more information.

Use part 661-2262 to repair the computer.

OK

Not okay.

once

Don’t use when you mean after.

Correct: After you turn on the computer…

Incorrect: Once you turn on the computer…

one-click (adj.)

OK to use to refer to actions or functions that are very simple.

From one-click fixes to detailed editing, there are a number of tools available in Photos.

Don’t use 1-Click.

opening display

Not splash screen. Opening display, startup display, and startup screen are all OK.

optionally

Avoid in user materials. Instead, describe the reason the user would perform the action. If it’s important to emphasize that the action is optional, you can say If you want to…

Correct: If you want to set a disk quota, enter the number and specify megabytes (MB) or gigabytes (GB).

Incorrect: Optionally, enter a disk quota and specify megabytes (MB) or gigabytes (GB).

Correct: To set a trust level, enter the command in Terminal.

Incorrect: Optionally, set the trust level by entering the command in Terminal.

over

Don’t use when you mean more than.

Correct: You can add more than 1000 songs.

Incorrect: You can add over 1000 songs.

pillarboxing (n.), pillarbox (v., adj.), pillarboxed (adj.)

Refers to the black bars placed at the sides of video to preserve the original aspect ratio when the video is presented in a format with a wider aspect ratio.

Pillarboxing allows 4:3 video to be displayed in a widescreen format.

You can pillarbox video with a 4:3 aspect ratio to display it in a widescreen format.

You can crop the video image to remove the pillarbox area (the black bars at the sides of the image).

placeholder names

When referring to interface text that varies depending on the context, use italic, lowercase text enclosed in brackets (don’t italicize the brackets).

Choose File > [filename].

Choose File > Export To > [submenu item].

Select the “Show last [numeral] photos” checkbox.

Don’t use brackets with placeholders in pathnames and filenames.

Users/username/Library/

The file is saved as filename.apmetadata.

please

Avoid using please in instructional text and cross-references.

Correct: Follow the steps below.

Incorrect: Please follow the steps below.

Correct: For more information, see “Store Settings” on page 96.

Incorrect: For more information, please see “Store Settings” on page 96.

possessives

Follow these guidelines for possessives:

  • Singular nouns: Form the possessive of a singular noun, including one that ends in s, by adding an apostrophe and an s.

the device’s dock connector

the boss’s husband

  • Plural nouns: Form the possessive of a plural noun that ends in s by adding an apostrophe. Form the possessive of a plural noun that doesn’t end in s by adding an apostrophe and an s.

the students’ curriculum

children’s requirements

  • Proper nouns or names: Form the possessive of a singular proper noun or proper name, including one that ends in s, by adding an apostrophe and an s. Form the possessive of a plural proper noun or proper name by adding an apostrophe.

Susan Torres’s biography [singular]

the Joneses’ computer [plural]

  • Product names: Rewrite to avoid forming a possessive of any product name, trademarked or not (for example, don’t use Keynote’s slides).

prepositions

It’s OK to end a sentence with a preposition, especially when rewriting would produce a stiff-sounding phrase.

Play a trailer you’re working on.

Select the playlist you want to add songs to.

problem

Don’t use in phrases such as this is a known problem or this version fixes that problem. Use condition, issue, or situation. It’s OK to use problem in a general way, such as the following:

If you have a problem registering, try again in a few moments.

professional

Don’t shorten to pro.

Huh, so iPhone 11 Pro is not for professional.

prompt (n., v., adj.)

Avoid using prompt as a verb if you can simply tell users to do something, or if you can use friendlier wording such as when asked or you may be asked.

Avoid: Double-click the side button, and then enter your passcode when prompted.

Preferable: Double-click the side button, and then enter your passcode.

If you do use prompt, don’t make hardware or software the actor; instead, use passive voice.

Correct: If you select Image, you’re prompted to select an image file.

Incorrect: If you select Image, the app prompts you to select an image file.

It’s OK to use prompt as a noun or an adjective when referring to the prompt character in a command-line interface.

At the prompt, enter resetpassword and press Return.

You can change the prompt character from a bracket to a flashing gray bar.

quality

Don’t use quality alone as an adjective; include a modifier. The compound adjective is hyphenated.

broadcast-quality, high-quality, professional-quality

quit

Use quit to refer to stopping an app from running completely. Don’t use exit, exit from, or leave when you mean quit.

re (prefix)

Close up unless the resulting word creates another word.

reenter, reinstall, reevaluate

re-create (recreate), re-sort (resort)

recommend

When describing something users are encouraged to do, don’t use we recommend or Apple recommends; use recommended.

Correct: It’s recommended that you import video using the same camera you used to record it.

Incorrect: We recommend that you import video using the same camera you used to record it.

You can also use less formal phrases like it’s a good idea to.

It’s a good idea to create a password hint.

run (v.), running (adj.)

Use running for programs or processes that operate in the background and have no graphical interface.

Open Activity Monitor to see what processes are running.

  • Apps: Don’t use run to describe what a user does with an app (a program that has a graphical interface); say use instead.

Correct: Before installing the software, use Disk Utility to verify your disk.

Incorrect: Before installing the software, run Disk Utility.

Don’t use running to refer to an open app; use open.

Correct: Check to see whether any apps are open.

Incorrect: Check to see whether any apps are running.

  • Software versions: In user materials, avoid using running to refer to versions of the operating system or apps. Instead, use alternatives such as use, using, or installed. In server materials or materials for more technical users, it’s OK to use running to refer to versions of the operating system or apps.

Correct: If you’re using iTunes 10.11 or earlier, follow these instructions.

Incorrect: If you’re running iTunes 10.11 or earlier, follow these instructions.

Correct: To use Siri on your Mac, you must have macOS 10.12 or later installed.

Incorrect: To use Siri on your Mac, you must be running macOS 10.12 or later.

support

Avoid in user materials when you can use compatible, works with, or another appropriate word or phrase.

Avoid: The first-generation iPad didn’t support AirPlay Mirroring.

Preferable: AirPlay Mirroring works with iPad 2 or later.

Avoid: iMovie supports most QuickTime formats.

Preferable: You can use files in most QuickTime formats with iMovie.

tap (n., v.)

Use to refer to the act of quickly touching and releasing a touchscreen or trackpad. Users can tap with one or more fingers (depending on the device and the action the user is performing). Don’t use tap on.

Correct: Tap Return to move from one field to another.

Correct: To zoom in or out, double-tap with two fingers.

Incorrect: Tap on the video you want to play.

they, their

When referring to an individual of an unspecified gender, don’t use he, she, he or she, or he/she. First try to rewrite the sentence—for example, by using the plural form or the second person, by omitting the pronoun (or replacing it with an article), or by repeating the noun.

Avoid: You can search for a specific customer using his or her name or email address.

Preferable: You can search for a specific customer using a name or email address.

Preferable: You can search for a specific customer using that customer’s name or email address.

When revising a sentence isn’t possible or the result is awkward, it’s OK to use they as a singular and gender-neutral pronoun and their for the possessive.

Avoid: Provide your direct report with the temporary password, and instruct him or her to go to the website to reset his or her email and VPN accounts.

Avoid: Provide your direct report with the temporary password, and instruct the employee to go to the website to reset the employee’s email and VPN accounts.

Preferable: Provide your direct report with the temporary password, and instruct them to go to the website to reset their email and VPN accounts.

unavailable

Use to describe an item—such as a menu command or an option in a dialog—that the user can’t select or choose because certain conditions aren’t met.

The Copy command is unavailable if there’s no text selected.

uncheck

Don’t use; use deselect.

unclick

Don’t use; use deselect.

update

Use to refer to a minor software release that updates a version of software, but doesn’t upgrade it to the next major version.

macOS Mojave 10.14.1 is an update to macOS Mojave 10.14.

Don’t use maintenance release or dot release.

upgrade

Use to refer to a major version of a software product. For example, macOS Mojave is an upgrade to macOS High Sierra.

user name

Two words.

version number

Include a version number with software names as needed—for example, when describing a new version of a product or comparing two versions of a product. Otherwise the version number can usually be omitted.

Don’t include the word version or the letter v when you refer to versions of software—for example, Keynote 8.3, not Keynote version 8.3.

Compressor 4 includes support for 360° video.

Final Cut Pro is the software of choice for professional video editors.

When referring to a major release number (such as macOS 10.14 or iOS 12), omit any trailing .0 unless it’s needed for clarity.

Pages 6.0 must be installed before you update to Pages 6.1.

Earlier or later: Use earlier or later, rather than lower or higher or newer or older.

To use Handoff, you need iOS 8 or later.

The letter x: Except in developer materials, don’t use x to mean “any number,” as in 10.x; use a specific number or range of numbers.

we

Don’t use first person; rewrite in terms of the reader or the product.

Correct: For best results, the image should be at least 600 x 600 pixels.

Incorrect: We recommend that the image be at least 600 x 600 pixels.


Nico Prananta

Articles, drawings, and codes by Nico Prananta, a software developer (iOS and web) and digital artist (for fun!) in Basel, Switzerland. I'm on Twitter.

RSS Feeds