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.
Write like a knowledgeable colleague explaining something useful. We're developers writing for developers.
- Correct - Information is accurate
- Concise - Succinct without unnecessary words
- Complete - Includes enough detail to complete the task
- Clear - Easy to understand
- 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.
- 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."
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
- 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
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.
Write in US English with US grammar.
- 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
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
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)
Avoid unclear subjects:
- ❌ After enabling auto-log-out, your users are logged out
- ✅ When you enable auto-log-out, your users are logged out
- 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
- 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
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
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.
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
- 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"
Every page should answer two questions in the first paragraph:
- What will I learn? - State what the page covers
- Why does this matter? - Explain the benefit or use case
Good opening:
Docker Compose Watch automatically updates your running containers when
you change code. This eliminates the manual rebuild-restart cycle during
development.Weak opening:
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:
- Prerequisites
- Basic usage (show the simple case first)
- Advanced options (add complexity after basics are clear)
Jarring flow:
- Prerequisites
- Overview of all capabilities (too much before seeing it work)
- 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)
- 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."
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:
- State what you're doing (brief)
- Show the command or code
- Explain the result or key parts (if not obvious)
Example:
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.
- 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
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.
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.
- Use sentence case for table headings
- Don't leave cells empty - use "N/A" or "None" if needed
- Align decimals on the decimal point
- 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"
Start optional steps with "Optional." followed by the instruction:
1. Optional. Enter a description for the job.
- Use formal file type names: "a PNG file" not "a .png file"
- Use abbreviated units with spaces: "10 GB" not "10GB" or "10 gigabytes"
| 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 |
- Use "earlier" not "lower": Docker Desktop 4.1 and earlier
- Use "later" not "higher" or "above": Docker Desktop 4.1 and later
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) |
- tab vs view - Use "view" for major UI sections, "tab" for sub-sections
- toggle - You "turn on" or "turn off" a toggle
- 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)
- 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
- 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
- ✅ Direct and practical
- ✅ Conversational with active voice
- ✅ Specific and actionable
- ❌ Corporate-speak
- ❌ Condescending
- ❌ Overly formal
- ✅ 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)
- ❌ 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