docker-docs/STYLE.md

# Docker Documentation Style Guide

This guide consolidates voice, grammar, formatting, and terminology
standards for Docker documentation. Follow these guidelines to create
clear, consistent, and helpful content. For instructions on how to use
components, shortcodes, and other features, see [COMPONENTS.md](COMPONENTS.md).

## Voice and tone

Write like a knowledgeable colleague explaining something useful. We're
developers writing for developers.

### Core principles: The 4Cs

1. **Correct** - Information is accurate
2. **Concise** - Succinct without unnecessary words
3. **Complete** - Includes enough detail to complete the task
4. **Clear** - Easy to understand

### Writing approach

- **Be honest.** Give all the facts. Don't use misdirection or
  ambiguous statements.
- **Be concise.** Don't bulk up communication with fluffy words or
  complex metaphors. Get to the point.
- **Be relaxed.** Casual but not lazy, smart but not arrogant, focused
  but not cold. Be welcoming and warm.
- **Be inclusive.** Every person is part of our community, regardless
  of experience level.

### Tone guidelines

- Use a natural, friendly, and respectful tone
- Use contractions to sound conversational (it's, you're, don't)
- Avoid overdoing politeness - skip "please" in most technical documentation
- Be clear over comical
- Use positive language - emphasize what users can do, not what they can't

**Positive language example:**

Instead of: "Features such as Single Sign-on (SSO), Image Access
Management, Registry Access Management are not available in Docker Team
subscription."

Use: "Features such as Single Sign-on (SSO), Image Access Management,
Registry Access Management are available in Docker Business subscription."

### Avoiding marketing language

Documentation should be factual and direct, not promotional.

**Avoid hedge words** that overstate ease or capability:

- ❌ simply, just, easily, seamlessly (implies ease when it may not be
  easy)
- ❌ robust, powerful (marketing language)
- ✅ Instead: describe what it actually does

**Avoid excessive enthusiasm:**

- ❌ "powerful feature", "game-changing", "revolutionary", "amazing"
- ✅ Instead: describe the feature and its benefits factually

**Avoid meta-commentary:**

These phrases add no value - state the fact directly:

- ❌ "It's worth noting that..."
- ❌ "It's important to understand that..."
- ❌ "Keep in mind that..."
- ✅ Instead: state the information directly

### Voice and perspective

- **Use "you" not "we"**: Focus on what the user can do, not what "we"
  created
  - ❌ "We provide a feature that helps you deploy"
  - ✅ "Deploy your applications with..."
- **Avoid "please"**: Don't use in normal explanations or "please note"
  phrases
- **Write timelessly**: Avoid "currently" or "as of this writing" - the
  documentation describes the product as it is today

### Scope preservation

When updating existing documentation, resist the urge to expand
unnecessarily. Users value brevity.

**Understand the current document:**
Read it fully to grasp its scope, length, and character. Is it a minimal
how-to or a comprehensive reference?

**Match the existing character:**
If the document is brief and direct (90 lines), keep it that way. Don't
transform a focused guide into an exhaustive tutorial.

**Add only what's genuinely missing:**
Fill gaps, don't elaborate. If the document already covers a topic
adequately, don't expand it.

**Value brevity:**
Say what needs to be said, then stop. Not every topic needs
prerequisites, troubleshooting, best practices, and examples sections.

**Respect the original intent:**
The document exists in its current form for a reason. Improve it, don't
remake it.

Good additions fill genuine gaps. Bad additions change the document's
character. When in doubt, add less rather than more.

## Grammar and style

Write in US English with US grammar.

### Acronyms and initialisms

- Spell out lesser-known acronyms on first use, then follow with the
  acronym in parentheses: "single sign-on (SSO)"
- Don't spell out common acronyms like URL, HTML, API
- Use all caps for file type acronyms: JPEG, PNG
- Don't use apostrophes for plurals: URLs not URL's
- Avoid introducing acronyms in headings - introduce them in the body
  text that follows

### Capitalization

Use sentence case for almost everything: headings, titles, links, buttons,
navigation labels.

- Capitalize Docker solutions: Docker Desktop, Docker Hub, Docker Extensions
- Capitalize job titles only when they immediately precede a name:
  "Chief Executive Officer Scott Johnston" but "Scott Johnston, chief
  executive officer"
- Follow company capitalization preferences: DISH, bluecrux
- Match UI capitalization when referring to specific interface elements

### Contractions

Use contractions to maintain a conversational tone, but don't overdo it.

- Stay consistent - don't switch between "you are" and "you're" in the
  same content
- Avoid negative contractions when possible (can't, don't, won't) -
  rewrite to be positive
- Never contract a noun with a verb (your container is ready, not your
  container's ready)

### Dangling modifiers

Avoid unclear subjects:

- ❌ After enabling auto-log-out, your users are logged out
- ✅ When you enable auto-log-out, your users are logged out

### Dates and numbers

- Use US date format: June 26, 2021 or Jun. 26, 2021
- Spell out numbers one through nine, except in units: 4 MB
- Use numerals for 10 and above: 10, 625, 1000
- Use decimals instead of fractions: 0.5 not ½
- For numbers with five or more digits, use spaces instead of commas:
  14 586 not 14,586
- For version numbers: version 4.8.2, v1.0, Docker Hub API v2

### Punctuation

- **Commas:** Use the Oxford comma (serial comma) in lists
- **Colons:** Use to introduce lists or provide explanations
- **Semicolons:** Don't use - write two sentences instead
- **Em dashes:** Use sparingly with spaces on either side: "text - like
  this - text"
- **Hyphens:** Use for compound adjectives before nouns:
  "up-to-date documentation"
- **Exclamation marks:** Avoid
- **Parentheses:** Avoid in technical documentation - they reduce
  readability

### Conciseness and redundant phrases

Remove unnecessary words to make documentation clearer and more direct.

**Eliminate redundant phrases:**

- ❌ "in order to" → ✅ "to"
- ❌ "serves the purpose of" → ✅ state what it does directly
- ❌ "allows you to" → ✅ "lets you" or state what it does
- ❌ "enables you to" → ✅ "lets you" or state what it does

### Bold and italics

Use bold **only** for UI elements (buttons, menus, field labels). Never
use bold for emphasis, product names, or feature names.

- ✅ Select **Save** (UI button - use bold)
- ✅ Docker Hub provides storage (product name - no bold)
- ✅ This is important to understand (emphasis - no bold)
- ❌ **Docker Desktop** is a tool (product name - don't bold)
- ❌ This is **very important** (emphasis - don't bold)
- ❌ The **build** command (command name - don't bold)

**Italics:**
Use italics sparingly, as this formatting can be difficult to read in
digital experiences. Notable exceptions are titles of articles, blog
posts, or specification documents.

## Formatting

### Content types and detail balance

Different content types require different writing approaches. Match your
style and detail level to the content type.

**Getting Started / Tutorials:**

- Step-by-step instructions
- Assume beginner knowledge
- Explain _why_ at each step
- Include more context and explanation

**How-to Guides:**

- Task-focused and goal-oriented
- Assume intermediate knowledge
- Focus on _how_ efficiently
- Less explanation, more direct steps

**Reference Documentation:**

- Comprehensive and exhaustive
- Assume advanced knowledge
- Focus on _what_ precisely
- Complete parameter lists and options

**Concept Explanations:**

- Educational and foundational
- Any skill level
- Focus on _understanding_ over doing
- Theory before practice

**Match detail to context:**

- **First mention** of a concept: explain it
- **Subsequent mentions**: link to the explanation or use the term
  directly if recently explained
- **Common knowledge** (to your audience): state it, don't explain it
- **Edge cases**: mention them but don't let them dominate the main flow

### Headings

- Keep headings short (no more than eight words)
- Front-load the most important words
- Use descriptive, action-oriented language
- Skip leading articles (a, the)
- Avoid puns, teasers, and cultural references
- Page titles should be action-oriented: "Install Docker Desktop",
  "Enable SCIM"

### Page structure and flow

Every page should answer two questions in the first paragraph:

1. **What will I learn?** - State what the page covers
2. **Why does this matter?** - Explain the benefit or use case

**Good opening:**

```markdown
Docker Compose Watch automatically updates your running containers when
you change code. This eliminates the manual rebuild-restart cycle during
development.
```

**Weak opening:**

```markdown
Docker Compose Watch is a powerful feature that enables developers to
streamline their development workflow by providing automatic
synchronization capabilities.
```

**Transitions and flow:**
Connect ideas naturally. Each section should flow logically from the
previous one. Save detailed discussions for after showing basic usage -
don't front-load complexity.

**Good flow:**

1. Prerequisites
2. Basic usage (show the simple case first)
3. Advanced options (add complexity after basics are clear)

**Jarring flow:**

1. Prerequisites
2. Overview of all capabilities (too much before seeing it work)
3. Basic usage

**Avoid structural problems:**

- Don't start multiple sentences or sections with the same structure
  (varies pacing and improves readability)
- Don't over-explain obvious things (trust the reader's competence)
- Don't use "**Bold:** format" for subsection labels (use plain text
  with colon)

### Lists

- Limit bulleted lists to five items when possible
- Don't add commas or semicolons to list item ends
- Capitalize list items for ease of scanning
- Make all list items parallel in structure
- Start each item with a capital letter unless it's a parameter or
  command
- For nested sequential lists, use lowercase letters: 1. Top level,
  a. Child step

**Avoid marketing-style list formatting:**

Don't use "**Term** - Description" format, which reads like marketing
copy:

❌ **Bad example:**

- **Build** - Creates images from Dockerfiles
- **Run** - Starts containers from images
- **Push** - Uploads images to registries

✅ **Good alternatives:**

Use simple descriptive bullets:

- Build images from Dockerfiles
- Start containers from images
- Upload images to registries

Or use proper prose when appropriate:
"Docker lets you build images from Dockerfiles, start containers from
images, and upload images to registries."

### Code and commands

Format Docker commands, instructions, filenames, and package names as
inline code using backticks: `docker build`

**Code example pattern:**

Follow this three-step pattern for code examples:

1. **State** what you're doing (brief)
2. **Show** the command or code
3. **Explain** the result or key parts (if not obvious)

**Example:**

````markdown
Build your image:

```console
$ docker build -t my-app .
```

This creates an image tagged `my-app` using the Dockerfile in the
current directory.
````

**When to show command output:**

- Show output when it helps understanding
- Show output when users need to verify results
- Don't show output for commands with obvious results
- Don't show output when it's not relevant to the point

For code block syntax, language hints, variables, and advanced features
(line highlighting, collapsible blocks), see
[COMPONENTS.md](COMPONENTS.md#code-blocks).

### Links

- Use plain, descriptive language (around five words)
- Front-load important terms at the beginning
- Avoid generic calls to action like "click here" or "find out more"
- Don't include end punctuation in link text
- Use relative links with source filenames for internal links
- Don't make link text bold or italic unless it would be in normal
  body copy

### Images

**Best practices:**

- Capture only relevant UI - don't include unnecessary white space
- Use realistic text, not lorem ipsum
- Keep images small and focused
- Compress images before adding to repository
- Remove unused images from repository

For image syntax and parameters (sizing, borders), see
[COMPONENTS.md](COMPONENTS.md#images).

### Callouts

Use callouts sparingly to emphasize important information. Use them only
when information truly deserves special emphasis - for warnings, critical
notes, or important context that affects how users approach a task.

Callout types: Note (informational), Tip (helpful suggestion), Important
(moderate issue), Warning (potential damage/loss), Caution (serious risk).

For syntax and detailed usage guidelines, see
[COMPONENTS.md](COMPONENTS.md#callouts).

### Tables

- Use sentence case for table headings
- Don't leave cells empty - use "N/A" or "None" if needed
- Align decimals on the decimal point

### Navigation instructions

- Use location, then action: "From the **Visibility** drop-down list, select Public"
- Be brief and specific: "Select **Save**"
- Start with the reason if a step needs one: "To view changes, select the link"

### Optional steps

Start optional steps with "Optional." followed by the instruction:

_1. Optional. Enter a description for the job._

### File types and units

- Use formal file type names: "a PNG file" not "a .png file"
- Use abbreviated units with spaces: "10 GB" not "10GB" or
  "10 gigabytes"

## Word list

### Recommended terms

| Use                                   | Don't use              |
| ------------------------------------- | ---------------------- |
| lets                                  | allows                 |
| turn on, toggle on                    | enable                 |
| turn off, toggle off                  | disable                |
| select                                | click                  |
| following                             | below                  |
| previous                              | above                  |
| checkbox                              | check box              |
| username                              | account name           |
| sign in                               | sign on, log in, login |
| sign up, create account               | register               |
| for example, such as                  | e.g.                   |
| run                                   | execute                |
| want                                  | wish                   |
| Kubernetes                            | K8s                    |
| repository                            | repo                   |
| administrator (first use), admin (UI) | -                      |
| and                                   | & (ampersand)          |
| move through, navigate to             | scroll                 |
| (be more precise)                     | respectively           |
| versus                                | vs, vs.                |
| use                                   | utilize                |
| help                                  | facilitate             |

### Version numbers

- Use "earlier" not "lower": Docker Desktop 4.1 and earlier
- Use "later" not "higher" or "above": Docker Desktop 4.1 and later

### Quick transformations

Common phrases to transform for clearer, more direct writing:

| Instead of...            | Write...                     |
| ------------------------ | ---------------------------- |
| In order to build        | To build                     |
| This allows you to build | This lets you build / Build  |
| Simply run the command   | Run the command              |
| We provide a feature     | Docker provides / You can    |
| Utilize the API          | Use the API                  |
| This facilitates testing | This helps test / This tests |
| Click the button         | Select the button            |
| It's worth noting that X | X (state it directly)        |

### UI elements

- **tab vs view** - Use "view" for major UI sections, "tab" for
  sub-sections
- **toggle** - You "turn on" or "turn off" a toggle

## Docker terminology

### Products and features

- **Docker Compose** - The application or all functionality associated
  with it
- **`docker compose`** - Use code formatting for commands
- **Docker Compose CLI** - The family of Compose commands from
  Docker CLI
- **Compose plugin** - The add-on for Docker CLI that can be
  enabled/disabled
- **compose.yaml** - Current designation for the Compose file (use
  code formatting)

### Technical terms

- **Digest** - Long string automatically created when you push an
  image
- **Member** - A user of Docker Hub who is part of an organization
- **Namespace** - Organization or user name; every image needs a
  namespace
- **Node** - Physical or virtual machine running Docker Engine in
  swarm mode
  - Manager nodes: Perform swarm management and orchestration
  - Worker nodes: Execute tasks
- **Registry** - Online storage for Docker images
- **Repository** - Lets users share container images with team,
  customers, or community

### Platform terminology

- **Multi-platform** - Broad: Mac/Linux/Windows; Narrow: Linux/amd64
  and Linux/arm64
- **Multi-architecture (multi-arch)** - CPU architecture or
  hardware-architecture-based; don't use as synonym for multi-platform

## Quick reference

### Voice checklist

- ✅ Direct and practical
- ✅ Conversational with active voice
- ✅ Specific and actionable
- ❌ Corporate-speak
- ❌ Condescending
- ❌ Overly formal

### Structure checklist

- ✅ Answer "What will I learn?" in the first paragraph
- ✅ Answer "Why does this matter?" in the first paragraph
- ✅ Front-load important information in headings and lists
- ✅ Connect ideas naturally between sections
- ✅ Use examples to clarify concepts
- ✅ Match content type (tutorial vs how-to vs reference vs concept)
- ✅ Follow code example pattern: state → show → explain
- ✅ Preserve document scope (don't unnecessarily expand)

### Common mistakes

- ❌ Using "click" instead of "select"
- ❌ Using "below" instead of "following"
- ❌ Starting sentences with numbers (recast the sentence)
- ❌ Using apostrophes in plural acronyms
- ❌ Leaving table cells empty
- ❌ Using commas in large numbers (use spaces)
- ❌ Referring to file types by extension (.png file)
- ❌ Using bold for product names or emphasis (only for UI elements)
- ❌ Using "**Term** - Description" format in lists
- ❌ Using hedge words (simply, easily, just, seamlessly)
- ❌ Using meta-commentary (it's worth noting that...)
- ❌ Using "we" instead of "you" or "Docker"
- ❌ Showing command output when it's not needed
- ❌ Not explaining what users will learn in first paragraph