STYLE.md
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.
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:
Avoid excessive enthusiasm:
Avoid meta-commentary:
These phrases add no value - state the fact directly:
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.
Use sentence case for almost everything: headings, titles, links, buttons, navigation labels.
Use contractions to maintain a conversational tone, but don't overdo it.
Avoid unclear subjects:
Remove unnecessary words to make documentation clearer and more direct.
Eliminate redundant phrases:
Use bold only for UI elements (buttons, menus, field labels). Never use bold for emphasis, product names, or feature names.
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:
How-to Guides:
Reference Documentation:
Concept Explanations:
Match detail to context:
Every page should answer two questions in the first paragraph:
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:
Jarring flow:
Avoid structural problems:
Avoid marketing-style list formatting:
Don't use "Term - Description" format, which reads like marketing copy:
❌ Bad example:
✅ Good alternatives:
Use simple descriptive bullets:
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:
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:
For code block syntax, language hints, variables, and advanced features (line highlighting, collapsible blocks), see COMPONENTS.md.
Best practices:
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.
Start optional steps with "Optional." followed by the instruction:
1. Optional. Enter a description for the job.
| 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 |
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) |
docker compose - Use code formatting for commands