Apple Style Guide — UX-Focused Documentation Standards

In this tutorial, you will learn about Apple Style Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

The Apple Style Guide focuses on user experience, simplicity, and task-oriented writing. It is designed for documentation that accompanies consumer products and emphasizes clarity for non-technical audiences.

In this lesson, you will learn the key rules from Apple's guide and how they differ from developer-focused guides.

What You'll Learn

You will understand Apple's task-oriented approach, apply its UI terminology rules, and know when Apple's guide is the right choice for your documentation.

Why It Matters

Apple's guide excels for consumer-facing documentation where user experience is paramount. Its rules make instructions easy to follow for non-technical readers.

Real-World Use

DodaTech applied Apple's menu path notation for the Doda Browser interface documentation. Users found configuration options 40 percent faster.

flowchart LR
  A[Apple Style Guide] --> B[Task-Oriented]
  A --> C[UI Terminology]
  A --> D[Simplicity]
  B --> E[Set up your account]
  C --> F[Choose File > Save]
  D --> G[One step at a time]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Task-Oriented Writing

Write instructions from the user's perspective. Focus on what the user wants to accomplish, not what the software can do.

Headings should describe tasks, not features. Set up your account not Account Settings Configuration.

Use imperative mood for instructions. Click Save not You should click Save. Direct commands are clearer.

# Apple Style: Task-Oriented Headings

# Good: Task-focused
## Set Up Your Account
## Configure Email Notifications
## Reset Your Password

# Bad: Feature-focused
## Account Settings
## Email Configuration Options
## Password Management

UI Terminology

Use menu paths consistently. Choose File > Save not Click File then click Save.

Be consistent with touch terminology. Use tap on iOS, click on macOS. Do not mix them.

Avoid file extensions in user-facing text. Open the document not Open the .docx file.

Use system-consistent terminology. Use the names that appear in the interface. Do not invent alternative names.

# Apple Style: UI Terminology

# Good menu paths
- Choose File > Save As
- Select Edit > Find > Find and Replace

# Good touch terminology
- Tap the Settings icon
- Swipe left to delete

# Avoid
- Click the File menu then click Save As
- Touch the Settings icon (on macOS)

Simplicity Principles

Use the simplest possible language. Remove unnecessary words. Start by opening the application becomes Open the application.

One instruction per step. Do not combine actions. Save the file. Close the window. Not Save the file and close the window.

Use the active voice. The user should click becomes Click. Direct address is always clearer.

# Apple Style: Simple instructions
# Avoid: You should now proceed to install the application by running
# the following command in your terminal application.

# Use: Install the application.
pip install dodazip

Common Mistakes

1. Feature-Focused Instead of Task-Focused

Writing about what the software can do instead of what the user wants to accomplish.

2. Inconsistent UI Terms

Using tap and click interchangeably. Using different names for the same interface element.

3. Showing File Extensions

Writing .docx, .pdf in user-facing text. Users do not need to see extensions.

4. Multiple Actions Per Step

Save and close and exit all in one step. Split into individual steps.

5. Menu Path Inconsistency

Sometimes using > notation, sometimes using arrow notation, sometimes describing clicks.

6. Platform Confusion

Writing iOS instructions for macOS users or vice versa.

7. Using Technical Jargon

Using API, endpoint, parameter in consumer-facing documentation.

Practice Questions

1. What is task-oriented writing?

Writing from the user's perspective focused on what they want to accomplish, not what the software can do.

2. How should menu paths be formatted?

Using greater-than notation: File > Save As rather than Click File then click Save As.

3. When should you use tap vs click?

Tap for touch interfaces like iOS and iPadOS. Click for pointer-based interfaces like macOS.

4. Why avoid file extensions in user-facing text?

Users care about documents, not file formats. Extensions add unnecessary technical detail.

5. Challenge: Take a feature-focused page of documentation and rewrite it in task-oriented style following Apple's guide. Replace feature headings with task headings and simplify instructions.

FAQ

Mini Project

Evaluate a page of consumer-facing documentation against Apple's style guide. Identify violations of task-oriented writing, UI terminology, and simplicity principles. Rewrite the page applying Apple's rules.

What's Next

Next: Chicago Manual of Style for Technical Writing