centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-03-27 14:28:47 +07:00
Code Issues Packages Projects Releases Wiki Activity

chore: refactor style guide to STYLE.md and COMPONENTS.md

Browse Source 
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson
2026-02-05 09:34:27 +01:00
parent e4cecc549e
commit 9f380d429e
34 changed files with 1252 additions and 2543 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
.github/instructions/styleguide-instructions.md vendored
View File

@@ -1,111 +0,0 @@
---
applyTo: '**/*.md'
---
# Documentation Writing Instructions
These are our documentation writing style guidelines.
## General Style tips
* Get to the point fast.
* Talk like a person.
* Simpler is better.
* Be brief. Give customers just enough information to make decisions confidently. Prune every excess word.
* We use Hugo to generate our docs.
## Grammar
* Use present tense verbs (is, open) instead of past tense (was, opened).
* Write factual statements and direct commands. Avoid hypotheticals like "could" or "would".
* Use active voice where the subject performs the action.
* Write in second person (you) to speak directly to readers.
* Use gender-neutral language.
* Avoid multiple -ing words that can create ambiguity.
* Keep prepositional phrases simple and clear.
* Place modifiers close to what they modify.
## Capitalization
* Use sentence-style capitalization for everything except proper nouns.
* Always capitalize proper nouns.
* Don’t capitalize the spelled-out form of an acronym unless it's a proper noun.
* In programming languages, follow the traditional capitalization of keywords and other special terms.
* Don't use all uppercase for emphasis.
## Numbers
* Spell out numbers for zero through nine, unless space is limited. Use numerals for 10 and above.
* Spell out numbers at the beginning of a sentence.
* Spell out ordinal numbers such as first, second, and third. Don't add -ly to form adverbs from ordinal numbers.
## Punctuation
* Use short, simple sentences.
* End all sentences with a period.
* Use one space after punctuation marks.
* After a colon, capitalize only proper nouns.
* Avoid semicolons - use separate sentences instead.
* Use question marks sparingly.
* Don't use slashes (/) - use "or" instead.
## Text formatting
* UI elements, like menu items, dialog names, and names of text boxes, should be in bold text.
* Use code style for:
* Code elements, like method names, property names, and language keywords.
* SQL commands.
* Command-line commands.
* Database table and column names.
* Resource names (like virtual machine names) that shouldn't be localized.
* URLs that you don't want to be selectable.
* For code placeholders, if you want users to replace part of an input string with their own values, use angle brackets (less than < and greater than > characters) on that placeholder text.
* Don't apply an inline style like italic, bold, or inline code style to headings.
## Alerts
* Alerts are a Markdown extension to create block quotes that render with colors and icons that indicate the significance of the content. The following alert types are supported:
* `[!NOTE]` Information the user should notice even if skimming.
* `[!TIP]` Optional information to help a user be more successful.
* `[!IMPORTANT]` Essential information required for user success.
* `[!CAUTION]` Negative potential consequences of an action.
* `[!WARNING]` Dangerous certain consequences of an action.
## Links
* Links to other documentation articles should be relative, not absolute. Include the `.md` suffix.
* Links to bookmarks within the same article should be relative and start with `#`.
* Link descriptions should be descriptive and make sense on their own. Don't use "click here" or "this link" or "here".
## Images
* Use images only when they add value.
* Images have a descriptive and meaningful alt text that starts with "Screenshot showing" and ends with ".".
* Videos have a descriptive and meaningful alt text or title that starts with "Video showing" and ends with ".".
## Numbered steps
* Write complete sentences with capitalization and periods
* Use imperative verbs
* Clearly indicate where actions take place (UI location)
* For single steps, use a bullet instead of a number
* When allowed, use angle brackets for menu sequences (File > Open)
* When writing ordered lists, only use 1's.
## Terminology
* Use "Select" instead of "Click" for UI elements like buttons, menu items, links, dropdowns, and checkboxes.
* Use "might" instead of "may" for conditional statements.
* Avoid latin abbreviations like "e.g.". Use "for example" instead.
* Use the verb "to enable" instead "to allow" unless you're referring to permissions.
* Follow the terms and capitalization guidelines in #fetch [VS Code docs wiki](https://github.com/microsoft/vscode-docs/wiki/VS-Code-glossary)
## Complete style guide
Find all the details of the style guide in these files:
- `./content/contribute/style/grammar.md` – Grammar rules
- `./content/contribute/style/formatting.md` – Formatting rules
- `./content/contribute/style/recommended-words.md` – Approved words and phrasing
- `./content/contribute/style/voice-tone.md` – Voice and tone guidance

606
COMPONENTS.md Normal file
View File

@@ -0,0 +1,606 @@
# Docker Documentation Components Guide
This guide explains how to use components, shortcodes, and special features
when writing Docker documentation. For writing style and grammar, see
[STYLE.md](STYLE.md).
## Front matter
Every documentation page requires front matter at the top of the file.
### Required fields
```yaml
---
title: Install Docker Engine on Ubuntu
description: Instructions for installing Docker Engine on Ubuntu
keywords: requirements, apt, installation, ubuntu
---
```
| Field | Description |
| ----------- | ------------------------------------------------------------ |
| title | Page title, used in `<h1>` and `<title>` tag |
| description | SEO description (150-160 characters), added to HTML metadata |
| keywords | Comma-separated keywords for SEO |
### Optional fields
| Field | Description |
| --------------- | ------------------------------------------------------------------ |
| linkTitle | Shorter title for navigation and sidebar (if different from title) |
| weight | Controls sort order in navigation (lower numbers appear first) |
| aliases | List of URLs that redirect to this page |
| toc_min | Minimum heading level in table of contents (default: 2) |
| toc_max | Maximum heading level in table of contents (default: 3) |
| notoc | Set to `true` to disable table of contents |
| sitemap | Set to `false` to exclude from search engine indexing |
| sidebar.badge | Add badge to sidebar (see [Badges](#badges)) |
| sidebar.reverse | Reverse sort order of pages in section |
| sidebar.goto | Override sidebar link URL |
### Example with optional fields
```yaml
---
title: Install Docker Engine on Ubuntu
linkTitle: Install on Ubuntu
description: Instructions for installing Docker Engine on Ubuntu
keywords: requirements, apt, installation, ubuntu, install, uninstall
weight: 10
aliases:
- /engine/installation/linux/ubuntu/
- /install/linux/ubuntu/
toc_max: 4
params:
sidebar:
badge:
color: blue
text: Beta
---
```
## Shortcodes
Shortcodes are reusable components that add rich functionality to your
documentation.
### Tabs
Use tabs for platform-specific instructions or content variations.
**Example:**
{{< tabs >}}
{{< tab name="Linux" >}}
```console
$ docker run hello-world
```
{{< /tab >}}
{{< tab name="macOS" >}}
```console
$ docker run hello-world
```
{{< /tab >}}
{{< tab name="Windows" >}}
```powershell
docker run hello-world
```
{{< /tab >}}
{{< /tabs >}}
**Syntax:**
```markdown
{{</* tabs */>}}
{{</* tab name="Linux" */>}}
Content for Linux
{{</* /tab */>}}
{{</* tab name="macOS" */>}}
Content for macOS
{{</* /tab */>}}
{{</* /tabs */>}}
```
**Tab groups (synchronized selection):**
Use the `group` attribute to synchronize tab selection across multiple tab
sections:
```markdown
{{</* tabs group="os" */>}}
{{</* tab name="Linux" */>}}
Linux content for first section
{{</* /tab */>}}
{{</* tab name="macOS" */>}}
macOS content for first section
{{</* /tab */>}}
{{</* /tabs */>}}
{{</* tabs group="os" */>}}
{{</* tab name="Linux" */>}}
Linux content for second section
{{</* /tab */>}}
{{</* tab name="macOS" */>}}
macOS content for second section
{{</* /tab */>}}
{{</* /tabs */>}}
```
When a user selects "Linux" in the first section, all tabs in the "os" group
switch to "Linux".
### Accordion
Use accordions for collapsible content like optional steps or advanced
configuration.
**Example:**
{{< accordion title="Advanced configuration" >}}
```yaml
version: "3.8"
services:
web:
build: .
ports:
- "8000:8000"
```
{{< /accordion >}}
**Syntax:**
```markdown
{{</* accordion title="Advanced configuration" */>}}
Content inside the accordion
{{</* /accordion */>}}
```
### Include
Reuse content across multiple pages using the include shortcode. Include
files must be in the `content/includes/` directory.
**Syntax:**
```markdown
{{</* include "filename.md" */>}}
```
**Example:**
```markdown
{{</* include "install-prerequisites.md" */>}}
```
### Badges
Use badges to highlight new, beta, experimental, or deprecated content.
**Example:**
{{< badge color=blue text="Beta" >}}
{{< badge color=violet text="Experimental" >}}
{{< badge color=green text="New" >}}
{{< badge color=gray text="Deprecated" >}}
**Syntax:**
Inline badge:
```markdown
{{</* badge color=blue text="Beta" */>}}
```
Badge as link:
```markdown
[{{</* badge color=blue text="Beta feature" */>}}](link-to-page.md)
```
Sidebar badge (in front matter):
```yaml
---
title: Page title
params:
sidebar:
badge:
color: violet
text: Experimental
---
```
**Color options:**
- `blue` - Beta content
- `violet` - Experimental or early access
- `green` - New GA content
- `amber` - Warning or attention
- `red` - Critical
- `gray` - Deprecated
**Usage guidelines:**
- Use badges for no longer than 2 months post-release
- Use violet for experimental/early access features
- Use blue for beta features
- Use green for new GA features
- Use gray for deprecated features
### Summary bars
Summary bars indicate subscription requirements, version requirements, or
administrator-only features at the top of a page.
**Example:**
{{< summary-bar feature_name="Docker Scout" >}}
**Setup:**
1. Add feature to `/data/summary.yaml`:
```yaml
features:
Docker Scout:
subscription: Business
availability: GA
requires: "Docker Desktop 4.17 or later"
```
2. Add shortcode to page:
```markdown
{{</* summary-bar feature_name="Docker Scout" */>}}
```
**Attributes in summary.yaml:**
| Attribute | Description | Values |
| ------------ | ------------------------------------- | ------------------------------------------------- |
| subscription | Subscription tier required | All, Personal, Pro, Team, Business |
| availability | Product development stage | Experimental, Beta, Early Access, GA, Retired |
| requires | Minimum version requirement | String describing version (link to release notes) |
| for | Indicates administrator-only features | Administrators |
### Buttons
Create styled buttons for calls to action.
**Syntax:**
```markdown
{{</* button text="Download Docker Desktop" url="/get-docker/" */>}}
```
### Cards
Create card layouts for organizing content.
**Syntax:**
```markdown
{{</* card
title="Get started"
description="Learn Docker basics"
link="/get-started/"
*/>}}
```
### Icons
Use Material Symbols icons in your content.
**Syntax:**
```markdown
{{</* icon name="check_circle" */>}}
```
Browse available icons at
[Material Symbols](https://fonts.google.com/icons).
## Callouts
Use GitHub-style callouts to emphasize important information. Use sparingly -
only when information truly deserves special emphasis.
**Syntax:**
```markdown
> [!NOTE]
> This is a note with helpful context.
> [!TIP]
> This is a helpful suggestion or best practice.
> [!IMPORTANT]
> This is critical information users must understand.
> [!WARNING]
> This warns about potential issues or consequences.
> [!CAUTION]
> This is for dangerous operations requiring extreme care.
```
**When to use each type:**
| Type | Use for | Color |
| --------- | -------------------------------------------------------------- | ------ |
| Note | Information that may not apply to all readers or is tangential | Blue |
| Tip | Helpful suggestions or best practices | Green |
| Important | Issues of moderate magnitude | Yellow |
| Warning | Actions that may cause damage or data loss | Red |
| Caution | Serious risks | Red |
## Code blocks
Format code with syntax highlighting using triple backticks and language
hints.
### Language hints
Common language hints:
- `console` - Interactive shell with `$` prompt
- `bash` - Bash scripts
- `dockerfile` - Dockerfiles
- `yaml` - YAML files
- `json` - JSON data
- `go`, `python`, `javascript` - Programming languages
- `powershell` - PowerShell commands
**Interactive shell example:**
````markdown
```console
$ docker run hello-world
```
````
**Bash script example:**
````markdown
```bash
#!/usr/bin/bash
echo "Hello from Docker"
```
````
### Variables in code
Use `<VARIABLE_NAME>` format for placeholder values:
````markdown
```console
$ docker tag <IMAGE_NAME> <REGISTRY>/<IMAGE_NAME>:<TAG>
```
````
This syntax renders variables in a special color and font style.
### Highlighting lines
Highlight specific lines with `hl_lines`:
````markdown
```go {hl_lines=[3,4]}
func main() {
fmt.Println("Hello")
fmt.Println("This line is highlighted")
fmt.Println("This line is highlighted")
}
```
````
### Collapsible code blocks
Make long code blocks collapsible:
````markdown
```dockerfile {collapse=true}
# syntax=docker/dockerfile:1
FROM golang:1.21-alpine
RUN apk add --no-cache git
# ... more lines
```
````
## Images
Add images using standard Markdown syntax with optional query parameters for
sizing and borders.
**Basic syntax:**
```markdown
![Alt text description](/assets/images/image.png)
```
**With size parameters:**
```markdown
![Alt text](/assets/images/image.png?w=600&h=400)
```
**With border:**
```markdown
![Alt text](/assets/images/image.png?border=true)
```
**Combined parameters:**
```markdown
![Alt text](/assets/images/image.png?w=600&h=400&border=true)
```
**Best practices:**
- Store images in `/static/assets/images/`
- Use descriptive alt text for accessibility
- Compress images before adding to repository
- Capture only relevant UI, avoid unnecessary whitespace
- Use realistic text, not lorem ipsum
- Remove unused images from repository
## Videos
Embed videos using HTML video tags or platform-specific embeds.
**Local video:**
```html
<video controls width="100%">
<source src="/assets/videos/demo.mp4" type="video/mp4" />
</video>
```
**YouTube embed:**
```html
<iframe
width="560"
height="315"
src="https://www.youtube.com/embed/VIDEO_ID"
frameborder="0"
allow="autoplay; encrypted-media"
allowfullscreen
>
</iframe>
```
## Links
Use standard Markdown link syntax. For internal links, use relative paths
with source filenames.
**External link:**
```markdown
[Docker Hub](https://hub.docker.com/)
```
**Internal link (same section):**
```markdown
[Installation guide](install.md)
```
**Internal link (different section):**
```markdown
[Get started](/get-started/overview.md)
```
**Link to heading:**
```markdown
[Prerequisites](#prerequisites)
```
**Best practices:**
- Use descriptive link text (around 5 words)
- Front-load important terms
- Avoid generic text like "click here" or "learn more"
- Don't include end punctuation in link text
- Use relative paths for internal links
## Lists
### Unordered lists
```markdown
- First item
- Second item
- Third item
- Nested item
- Another nested item
```
### Ordered lists
```markdown
1. First step
2. Second step
3. Third step
1. Nested step
2. Another nested step
```
### Best practices
- Limit bulleted lists to 5 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
- For nested sequential lists, use lowercase letters (a, b, c)
## Tables
Use standard Markdown table syntax with sentence case for headings.
**Example:**
```markdown
| Feature | Description | Availability |
| -------------- | ------------------------------- | ------------ |
| Docker Compose | Multi-container orchestration | All |
| Docker Scout | Security vulnerability scanning | Business |
| Build Cloud | Remote build service | Pro, Team |
```
**Best practices:**
- Use sentence case for table headings
- Don't leave cells empty - use "N/A" or "None"
- Align decimals on the decimal point
- Keep tables scannable - avoid dense content
## Quick reference
### File structure
```plaintext
content/
├── manuals/ # Product documentation
│ ├── docker-desktop/
│ ├── docker-hub/
│ └── ...
├── guides/ # Learning guides
├── reference/ # API and CLI reference
└── includes/ # Reusable content snippets
```
### Common patterns
**Platform-specific instructions:**
Use tabs with consistent names: Linux, macOS, Windows
**Optional content:**
Use accordions for advanced or optional information
**Version/subscription indicators:**
Use badges or summary bars
**Important warnings:**
Use callouts (NOTE, WARNING, CAUTION)
**Code examples:**
Use `console` for interactive shells, appropriate language hints for code

9
CONTRIBUTING.md
View File

@@ -3,9 +3,12 @@
We value documentation contributions from the Docker community. We'd like to
make it as easy as possible for you to work in this repository.
Our style guide and instructions on using our page templates and components is
available in the [contribution section](https://docs.docker.com/contribute/) on
the website.
Before contributing, review our documentation standards:
- [STYLE.md](STYLE.md) - Writing style, voice, grammar, and formatting
guidelines
- [COMPONENTS.md](COMPONENTS.md) - How to use Hugo shortcodes, front matter,
and components
The following guidelines describe how to contribute to the
Docker documentation at <https://docs.docker.com/>, and how to get started.

7
README.md
View File

@@ -13,6 +13,7 @@ Feel free to open pull requests or issues. Our docs are completely open source,
## Provide feedback
We’d love to hear your feedback! To submit feedback:
- Click **[New issue](https://github.com/docker/docs/issues/new)** on the docs repository, or
- Click **Request changes** in the right column of every page on
[docs.docker.com](https://docs.docker.com/), or
@@ -28,7 +29,11 @@ repository.
## Contribute to Docker docs
See [CONTRIBUTING.md](CONTRIBUTING.md).
We welcome contributions! To get started:
- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution workflow and setup
- [STYLE.md](STYLE.md) - Writing style and content guidelines
- [COMPONENTS.md](COMPONENTS.md) - Component and shortcode usage
## Copyright and license

566
STYLE.md Normal file
View File

@@ -0,0 +1,566 @@
# 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

53
content/contribute/_index.md
View File

@@ -1,53 +0,0 @@
---
title: Contribute to Docker's docs
linkTitle: Contribute
weight: 10
toc_max: 1
aliases:
- /opensource/
- /contribute/overview/
- /contribute/contribute-guide/
grid:
- title: Grammar and style
description: Explore Docker's grammar and style guide
icon: menu_book
link: /contribute/style/grammar
- title: Formatting
description: Format your content to match the rest of our documentation.
icon: newspaper
link: /contribute/style/formatting
- title: Recommended word list
description: Choose the right words for your content.
icon: checklist
link: /contribute/style/recommended-words
- title: Source file conventions
description: Guidelines for creating a new page.
icon: note_add
link: /contribute/file-conventions
- title: Terminology
description: Explore commonly used Docker terms.
icon: spellcheck
link: /contribute/style/terminology
- title: Voice and tone
description: Learn about how we use voice and tone in our writing.
icon: voice_selection
link: /contribute/style/voice-tone
---
We value documentation contributions from the Docker community. We'd like to
make it as easy as possible for you to contribute to the Docker documentation.
Find the contribution guidelines in
[CONTRIBUTING.md](https://github.com/docker/docs/blob/main/CONTRIBUTING.md) in
the `docker/docs` GitHub repository. Use the following links to review our
style guide and instructions on how to use our page templates and components.
{{< grid >}}
### Additional resources
See also:
- A section of useful components you can add to your documentation.
- Information on Docker's [tone and voice](style/voice-tone.md).
- A [writing checklist](checklist.md) to help you when you're contributing to Docker's documentation.

55
content/contribute/checklist.md
View File

@@ -1,55 +0,0 @@
---
title: Writing checklist
description: A helpful writing checklist when creating documentation
keywords: checklist, documentation, style guide, contribute
weight: 60
---
Use this checklist to communicate in a way that is clear, helpful, and consistent with the rest of Docker Docs.
##### Used active voice
Active voice is specific and removes ambiguity.
In active voice, the subject of the sentence (the customer or the system) does the action.
Sentences that use active voice are easier to read. Active voice makes it clear who has done what and to whom. Plus, active voice keeps sentences direct and more concise.
Helping verbs such as is, was, or would may indicate that you're writing in passive voice. And, if you can add the phrase 'by zombies' after the verb, you're writing in the passive voice.
|Correct| Incorrect|
|:--|:--|
|Increase productivity with Docker Desktop.| Productivity can be increased (by zombies) with Docker Desktop.|
|If you remove items from a grid, charts automatically refresh to display the change. | If items are removed (by zombies) from a grid, charts automatically refresh to display the change.|
##### Written clear sentences that get to the point
Write short, concise sentences. Punchy sentences are faster to read and easier to understand.
##### Used subheadings and bulleted lists to break up the page
This helps find the information they need quickly and easily.
For more information, see the [formatting](style/formatting.md#headings-and-subheadings) page, or see the [components](components/lists.md) for examples.
##### Started the title of your page with a verb
For example, 'Install Docker Desktop'.
##### Checked that the left-hand table of contents title in docs.docker.com, matches the title displayed on the page
##### Checked for broken links and images
Use relative links to link to other pages or images within the GitHub repository.
For more information, see the [formatting](style/formatting.md#links) page, or see the [components](components/links.md) for examples.
##### Checked that any redirects you may have added, work
For information on how to add redirects, see [Source file conventions](file-conventions.md#front-matter).
##### Used bold on any UI elements you refer to in your content
##### Completed a final spelling, punctuation, and grammar check
For more in-depth information on our Style Guide, explore the [grammar](style/grammar.md) or [formatting](style/formatting.md) guides.

6
content/contribute/components/_index.md
View File

@@ -1,6 +0,0 @@
---
build:
render: never
title: Useful components
weight: 50
---

27
content/contribute/components/accordions.md
View File

@@ -1,27 +0,0 @@
---
description: components and formatting examples used in Docker's docs
title: Accordions
toc_max: 3
---
## Example
{{< accordion title="Accordion example" >}}
```console
$ docker run hello-world
```
{{< /accordion >}}
## Markup
````markdown
{{</* accordion title="Accordion example" */>}}
```console
$ docker run hello-world
```
{{</* /accordion */>}}
````

51
content/contribute/components/badges.md
View File

@@ -1,51 +0,0 @@
---
description: components and formatting examples used in Docker's docs
title: Badges
toc_max: 3
---
### Examples
{{< badge color=blue text="blue badge" >}}
{{< badge color=amber text="amber badge" >}}
{{< badge color=red text="red badge" >}}
{{< badge color=green text="green badge" >}}
{{< badge color=violet text="violet badge" >}}
{{< badge color=gray text="gray badge" >}}
You can also make a badge a link.
[{{< badge color="blue" text="badge with a link" >}}](../_index.md)
### Usage guidelines
Use badges to indicate new content and product content in various stages of the release lifecycle:
- The violet badge to highlight new early access or experimental content
- The blue badge to highlight beta content
- The green badge to highlight new content that is either GA or not product-related content, such as guides/learning paths
- The gray badge to highlight deprecated content
Best practice is to use this badge for no longer than 2 months post release of the feature.
### Markup
Inline badge:
```go
{{</* badge color=amber text="amber badge" */>}}
[{{</* badge color="blue" text="badge with a link" */>}}](../overview.md)
```
Sidebar badge in frontmatter:
```yaml
---
title: Page title
params:
sidebar:
badge:
color: gray
text: Deprecated
---
```

15
content/contribute/components/buttons.md
View File

@@ -1,15 +0,0 @@
---
description: components and formatting examples used in Docker's docs
title: Buttons
toc_max: 3
---
### Examples
{{< button url="https://example.com/" text="hello" >}}
### Markup
```go
{{</* button url="https://example.com/" text="hello" */>}}
```

103
content/contribute/components/call-outs.md
View File

@@ -1,103 +0,0 @@
---
description: components and formatting examples used in Docker's docs
title: Callouts
toc_max: 3
---
We support these broad categories of callouts:
- Alerts: Note, Tip, Important, Warning, Caution
We also support summary bars, which represent a feature's required subscription, version, or Adminstrator role.
To add a summary bar:
Add the feature name to the `/data/summary.yaml` file. Use the following attributes:
| Attribute | Description | Possible values |
|----------------|--------------------------------------------------------|---------------------------------------------------------|
| `subscription` | Notes the subscription required to use the feature | All, Personal, Pro, Team, Business |
| `availability` | Notes what product development stage the feature is in | Experimental, Beta, Early Access, GA, Retired |
| `requires` | Notes what minimum version is required for the feature | No specific value, use a string to describe the version and link to relevant release notes |
| `for` | Notes if the feature is intended for IT Administrators | Administrators |
Then, add the `summary-bar` shortcode on the page you want to add the summary bar to. Note, the feature name is case sensitive. The icons that appear in the summary bar are automatically rendered.
## Examples
{{< summary-bar feature_name="PKG installer" >}}
> [!NOTE]
>
> Note the way the `get_hit_count` function is written. This basic retry
> loop lets us attempt our request multiple times if the redis service is
> not available. This is useful at startup while the application comes
> online, but also makes our application more resilient if the Redis
> service needs to be restarted anytime during the app's lifetime. In a
> cluster, this also helps handling momentary connection drops between
> nodes.
> [!TIP]
>
> For a smaller base image, use `alpine`.
> [!IMPORTANT]
>
> Treat access tokens like your password and keep them secret. Store your
> tokens securely (for example, in a credential manager).
> [!WARNING]
>
> Removing Volumes
>
> By default, named volumes in your compose file are NOT removed when running
> `docker compose down`. If you want to remove the volumes, you will need to add
> the `--volumes` flag.
>
> The Docker Desktop Dashboard does not remove volumes when you delete the app stack.
> [!CAUTION]
>
> Here be dragons.
For both of the following callouts, consult [the Docker release lifecycle](/release-lifecycle) for more information on when to use them.
## Formatting
```md
{{</* summary-bar feature_name="PKG installer" */>}}
```
```html
> [!NOTE]
>
> Note the way the `get_hit_count` function is written. This basic retry
> loop lets us attempt our request multiple times if the redis service is
> not available. This is useful at startup while the application comes
> online, but also makes our application more resilient if the Redis
> service needs to be restarted anytime during the app's lifetime. In a
> cluster, this also helps handling momentary connection drops between
> nodes.
> [!TIP]
>
> For a smaller base image, use `alpine`.
> [!IMPORTANT]
>
> Treat access tokens like your password and keep them secret. Store your
> tokens securely (for example, in a credential manager).
> [!WARNING]
>
> Removing Volumes
>
> By default, named volumes in your compose file are NOT removed when running
> `docker compose down`. If you want to remove the volumes, you will need to add
> the `--volumes` flag.
>
> The Docker Desktop Dashboard does not remove volumes when you delete the app stack.
> [!CAUTION]
>
> Here be dragons.
```

97
content/contribute/components/cards.md
View File

@@ -1,97 +0,0 @@
---
description: components and formatting examples used in Docker's docs
title: Cards
toc_max: 3
grid:
- title: Docker Desktop
description: Docker on your Desktop.
icon: install_desktop
link: /desktop/
- title: Docker Engine
description: Vrrrrooooommm
icon: developer_board
link: /engine/
- title: Docker Build
description: Clang bang
icon: build
link: /build/
- title: Docker Compose
description: Figgy!
icon: account_tree
link: /compose/
- title: Docker Hub
description: so much content, oh wow
icon: hub
link: /docker-hub/
---
Cards can be added to a page using the `card` shortcode.
The parameters for this shortcode are:
| Parameter | Description |
| ----------- | -------------------------------------------------------------------- |
| title | The title of the card |
| icon | The icon slug of the card |
| image | Use a custom image instead of an icon (mutually exclusive with icon) |
| link | (Optional) The link target of the card, when clicked |
| description | A description text, in Markdown |
> [!NOTE]
>
> There's a known limitation with the Markdown description of cards,
> in that they can't contain relative links, pointing to other .md documents.
> Such links won't render correctly. Instead, use an absolute link to the URL
> path of the page that you want to link to.
>
> For example, instead of linking to `../install/linux.md`, write:
> `/engine/install/linux/`.
## Example
{{< card
title="Get your Docker on"
icon=favorite
link=https://docs.docker.com/
description="Build, share, and run your apps with Docker" >}}
## Markup
```go
{{</* card
title="Get your Docker on"
icon=favorite
link=https://docs.docker.com/
description="Build, share, and run your apps with Docker"
*/>}}
```
### Grid
There's also a built-in `grid` shortcode that generates a... well, grid... of cards.
The grid size is 3x3 on large screens, 2x2 on medium, and single column on small.
{{< grid >}}
Grid is a separate shortcode from `card`, but it implements the same component under the hood.
The markup you use to insert a grid is slightly unconventional. The grid shortcode takes no arguments.
All it does is let you specify where on a page you want your grid to appear.
```go
{{</* grid */>}}
```
The data for the grid is defined in the front matter of the page, under the `grid` key, as follows:
```yaml
# front matter section of a page
title: some page
grid:
- title: "Docker Engine"
description: Vrrrrooooommm
icon: "developer_board"
link: "/engine/"
- title: "Docker Build"
description: Clang bang
icon: "build"
link: "/build/"
```

244
content/contribute/components/code-blocks.md
View File

@@ -1,244 +0,0 @@
---
description: components and formatting examples used in Docker's docs
title: Code blocks
toc_max: 3
---
Rouge provides lots of different code block "hints". If you leave off the hint,
it tries to guess and sometimes gets it wrong. These are just a few hints that
we use often.
## Variables
If your example contains a placeholder value that's subject to change,
use the format `<[A-Z_]+>` for the placeholder value: `<MY_VARIABLE>`
```text
export name=<MY_NAME>
```
This syntax is reserved for variable names, and will cause the variable to
be rendered in a special color and font style.
## Highlight lines
```text {hl_lines=[7,8]}
incoming := map[string]interface{}{
"asdf": 1,
"qwer": []interface{}{},
"zxcv": []interface{}{
map[string]interface{}{},
true,
int(1e9),
"tyui",
},
}
```
````markdown
```go {hl_lines=[7,8]}
incoming := map[string]interface{}{
"asdf": 1,
"qwer": []interface{}{},
"zxcv": []interface{}{
map[string]interface{}{},
true,
int(1e9),
"tyui",
},
}
```
````
## Collapsible code blocks
```dockerfile {collapse=true}
# syntax=docker/dockerfile:1
ARG GO_VERSION="1.21"
FROM golang:${GO_VERSION}-alpine AS base
ENV CGO_ENABLED=0
ENV GOPRIVATE="github.com/foo/*"
RUN apk add --no-cache file git rsync openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts
WORKDIR /src
FROM base AS vendor
# this step configure git and checks the ssh key is loaded
RUN --mount=type=ssh <<EOT
set -e
echo "Setting Git SSH protocol"
git config --global url."git@github.com:".insteadOf "https://github.com/"
(
set +e
ssh -T git@github.com
if [ ! "$?" = "1" ]; then
echo "No GitHub SSH key loaded exiting..."
exit 1
fi
)
EOT
# this one download go modules
RUN --mount=type=bind,target=. \
--mount=type=cache,target=/go/pkg/mod \
--mount=type=ssh \
go mod download -x
FROM vendor AS build
RUN --mount=type=bind,target=. \
--mount=type=cache,target=/go/pkg/mod \
--mount=type=cache,target=/root/.cache \
go build ...
```
## Bash
Use the `bash` language code block when you want to show a Bash script:
```bash
#!/usr/bin/bash
echo "deb https://download.docker.com/linux/ubuntu noble stable" | sudo tee /etc/apt/sources.list.d/docker.list
```
If you want to show an interactive shell, use `console` instead.
In cases where you use `console`, make sure to add a dollar character
for the user sign:
```console
$ echo "deb https://download.docker.com/linux/ubuntu noble stable" | sudo tee /etc/apt/sources.list.d/docker.list
```
## Go
```go
incoming := map[string]interface{}{
"asdf": 1,
"qwer": []interface{}{},
"zxcv": []interface{}{
map[string]interface{}{},
true,
int(1e9),
"tyui",
},
}
```
## PowerShell
```powershell
Install-Module DockerMsftProvider -Force
Install-Package Docker -ProviderName DockerMsftProvider -Force
[System.Environment]::SetEnvironmentVariable("DOCKER_FIPS", "1", "Machine")
Expand-Archive docker-18.09.1.zip -DestinationPath $Env:ProgramFiles -Force
```
## Python
```python
return html.format(name=os.getenv('NAME', "world"), hostname=socket.gethostname(), visits=visits)
```
## Ruby
```ruby
docker_service 'default' do
action [:create, :start]
end
```
## JSON
```json
"server": {
"http_addr": ":4443",
"tls_key_file": "./fixtures/notary-server.key",
"tls_cert_file": "./fixtures/notary-server.crt"
}
```
#### HTML
```html
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
</head>
</html>
```
## Markdown
```markdown
# Hello
```
If you want to include a triple-fenced code block inside your code block,
you can wrap your block in a quadruple-fenced code block:
`````markdown
````markdown
# Hello
```go
log.Println("did something")
```
````
`````
## ini
```ini
[supervisord]
nodaemon=true
[program:sshd]
command=/usr/sbin/sshd -D
```
## Dockerfile
```dockerfile
# syntax=docker/dockerfile:1
FROM ubuntu
RUN apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys B97B0AFCAA1A47F044F244A07FCC7D46ACCC4CF8
RUN echo "deb http://apt.postgresql.org/pub/repos/apt/ precise-pgdg main" > /etc/apt/sources.list.d/pgdg.list
RUN apt-get update && apt-get install -y python-software-properties software-properties-common postgresql-9.3 postgresql-client-9.3 postgresql-contrib-9.3
# Note: The official Debian and Ubuntu images automatically ``apt-get clean``
# after each ``apt-get``
USER postgres
RUN /etc/init.d/postgresql start &&\
psql --command "CREATE USER docker WITH SUPERUSER PASSWORD 'docker';" &&\
createdb -O docker docker
RUN echo "host all all 0.0.0.0/0 md5" >> /etc/postgresql/9.3/main/pg_hba.conf
RUN echo "listen_addresses='*'" >> /etc/postgresql/9.3/main/postgresql.conf
EXPOSE 5432
VOLUME ["/etc/postgresql", "/var/log/postgresql", "/var/lib/postgresql"]
CMD ["/usr/lib/postgresql/9.3/bin/postgres", "-D", "/var/lib/postgresql/9.3/main", "-c", "config_file=/etc/postgresql/9.3/main/postgresql.conf"]
```
## YAML
```yaml
authorizedkeys:
image: dockercloud/authorizedkeys
deployment_strategy: every_node
autodestroy: always
environment:
- AUTHORIZED_KEYS=ssh-rsa AAAAB3Nsomelongsshkeystringhereu9UzQbVKy9o00NqXa5jkmZ9Yd0BJBjFmb3WwUR8sJWZVTPFL
volumes:
/root:/user:rw
```

151
content/contribute/components/icons.md
View File

@@ -1,151 +0,0 @@
---
description: Icons used across docs
title: Icons
grid:
- title: "Install"
icon: "download"
description: Icon name = download
- title: "FAQs"
icon: "help"
description: Icon name = help
- title: "Onboarding/quickstarts"
icon: "explore"
description: Icon name = explore
- title: "Release notes"
icon: "note_add"
description: Icon name = note_add
- title: "Feedback"
icon: "sms"
description: Icon name = sms
- title: "Multi-platform/arch"
icon: "content_copy"
description: Icon name = content_copy
- title: "Rootless/ECI"
icon: "security"
description: Icon name = security
- title: "Settings management"
icon: "shield_lock"
description: Icon name = shield_lock
- title: "Processes"
icon: "checklist"
description: Icon name = checklist
- title: "Networking"
icon: "network_node"
description: Icon name = network_node
- title: "Exploring a feature"
icon: "feature_search"
description: Icon name = feature_search
- title: "Company"
icon: "apartment"
description: Icon name = apartment
- title: "Organization"
icon: "store"
description: Icon name = store
- title: "Additional resources"
icon: "category"
description: Icon name = category
- title: "Designing"
icon: "design_services"
description: Icon name = design_services
- title: "Publishing"
icon: "publish"
description: Icon name = publish
- title: "Interacting"
icon: "multiple_stop"
description: Icon name = multiple_stop
- title: "Storage"
icon: "database"
description: Icon name = database
- title: "logs"
icon: "text_snippet"
description: Icon name = text_snippet
- title: "Prune/cut"
icon: "content_cut"
description: Icon name = content_cut
- title: "Configure"
icon: "tune"
description: Icon name = tune
- title: "Deprecated"
icon: "folder_delete"
description: Icon name = folder_delete
- title: "RAM"
icon: "home_storage"
description: Icon name = home_storage
- title: "IAM"
icon: "photo_library"
description: Icon name = photo_library
- title: "Packaging"
icon: "inventory_2"
description: Icon name = inventory_2
- title: "Multi-stage"
icon: "stairs"
description: Icon name = stairs
- title: "Architecture"
icon: "construction"
description: Icon name = construction
- title: "Build drivers"
icon: "engineering"
description: Icon name = engineering
- title: "Export"
icon: "output"
description: Icon name = output
- title: "Cache"
icon: "cycle"
description: Icon name = cycle
- title: "Bake"
icon: "cake"
description: Icon name = cake
- title: "Docker ID"
icon: "fingerprint"
description: Icon name = fingerprint
- title: "Repository"
icon: "inbox"
description: Icon name = inbox
- title: "Access tokens"
icon: "password"
description: Icon name = password
- title: "official images"
icon: "verified"
description: Icon name = verified
- title: "Hardened Docker Desktop"
icon: "lock"
description: Icon name = lock
- title: "Sign in"
icon: "passkey"
description: Icon name = passkey
- title: "SSO and SCIM"
icon: "key"
description: Icon name = key
- title: "2FA"
icon: "phonelink_lock"
description: Icon name = phonelink_lock
- title: "Add/update payment method"
icon: "credit_score"
description: Icon name = credit_score
- title: "Update billing info"
icon: "contract_edit"
description: Icon name = contract_edit
- title: "Billing history"
icon: "payments"
description: Icon name = payments
- title: "Upgrade"
icon: "upgrade"
description: Icon name = upgrade
- title: "Add/manage more seats/users"
icon: "group_add"
description: Icon name = group_add
- title: "Domains"
icon: "domain_verification"
description: Icon name = domain_verification
- title: Company owner
description: Icon name = supervised_user_circle
icon: supervised_user_circle
- title: "General settings"
icon: "settings"
description: Icon name = settings
---
Below is an inventory of the icons we use to represent different topics or features across docs. To be used with the [cards component](cards.md).
{{< grid >}}

40
content/contribute/components/images.md
View File

@@ -1,40 +0,0 @@
---
description: components and formatting examples used in Docker's docs
title: Images
toc_max: 3
---
## Example
- A small image: ![a small image](/assets/images/footer_moby_icon.png)
- Large images occupy the full width of the reading column by default:
![a pretty wide image](/assets/images/banner_image_24512.png)
- Image size can be set using query parameters: `?h=<height>&w=<width>`
![a pretty wide image](/assets/images/banner_image_24512.png?w=100&h=50)
- Image with a border, also set with a query parameter: `?border=true`
![a small image](/assets/images/footer_moby_icon.png?border=true)
## HTML and Markdown
```markdown
- A small image: ![a small image](/assets/images/footer_moby_icon.png)
- Large images occupy the full width of the reading column by default:
![a pretty wide image](/assets/images/banner_image_24512.png)
- Image size can be set using query parameters: `?h=<height>&w=<width>`
![a pretty wide image](/assets/images/banner_image_24512.png?w=100&h=50)
- Image with a border, also set with a query parameter: `?border=true`
![a small image](/assets/images/footer_moby_icon.png?border=true)
```

26
content/contribute/components/links.md
View File

@@ -1,26 +0,0 @@
---
description: components and formatting examples used in Docker's docs
title: Links
toc_max: 3
---
## Examples
[External links](https://docker.com) and [internal links](links.md) both
open in the same tab.
Use relative links, using source filenames.
#### Links to auto-generated content
When you link to heading IDs in auto-generated pages, such as CLI
reference content, you won't get any help from your editor in resolving the
anchor names. That's because the pages are generated at build-time and your
editor or LSP doesn't know about them in advance.
## Syntax
```md
[External links](https://docker.com)
[Internal links](links.md)
```

79
content/contribute/components/lists.md
View File

@@ -1,79 +0,0 @@
---
description: components and formatting examples used in Docker's docs
title: Lists
toc_max: 3
---
## Examples
Use dashes (`-`) or asterisks (`*`) for bullet points.
- Bullet list item 1
- Bullet list item 2
- Bullet list item 3
1. Numbered list item 1. Two spaces between the period and the first letter
helps with alignment.
2. Numbered list item 2. Let's put a note in it.
> [!NOTE]: We did it!
3. Numbered list item 3 with a code block in it. You need the blank line before
the code block happens.
```bash
$ docker run hello-world
```
4. Numbered list item 4 with a bullet list inside it and a numbered list
inside that.
- Sub-item 1
- Sub-item 2
1. Sub-sub-item 1
2. Sub-sub-item-2 with a table inside it because we like to party!
Indentation is super important.
| Header 1 | Header 2 |
| -------- | -------- |
| Thing 1 | Thing 2 |
| Thing 3 | Thing 4 |
## Markdown
````md
- Bullet list item 1
- Bullet list item 2
- Bullet list item 3
1. Numbered list item 1. Two spaces between the period and the first letter
helps with alignment.
2. Numbered list item 2. Let's put a note in it.
> [!NOTE]: We did it!
3. Numbered list item 3 with a code block in it. You need the blank line before
the code block happens.
```bash
$ docker run hello-world
```
4. Numbered list item 4 with a bullet list inside it and a numbered list
inside that.
- Sub-item 1
- Sub-item 2
1. Sub-sub-item 1
2. Sub-sub-item-2 with a table inside it.
Indentation is super important.
| Header 1 | Header 2 |
| -------- | -------- |
| Thing 1 | Thing 2 |
| Thing 3 | Thing 4 |
````

54
content/contribute/components/tables.md
View File

@@ -1,54 +0,0 @@
---
description: components and formatting examples used in Docker's docs
title: Tables
toc_max: 3
---
## Example
### Basic table
| Permission level | Access |
| :----------------------------------------------------------------------- | :------------------------------------------------------------ |
| **Bold** or _italic_ within a table cell. Next cell is empty on purpose. | |
| | Previous cell is empty. A `--flag` in mono text. |
| Read | Pull |
| Read/Write | Pull, push |
| Admin | All of the above, plus update description, create, and delete |
### Feature-support table
| Platform | x86_64 / amd64 |
| :--------- | :------------: |
| Ubuntu | ✅ |
| Debian | ✅ |
| Fedora | |
| Arch (btw) | ✅ |
## Markdown
### Basic table
```md
| Permission level | Access |
| :----------------------------------------------------------------------- | :------------------------------------------------------------ |
| **Bold** or _italic_ within a table cell. Next cell is empty on purpose. | |
| | Previous cell is empty. A `--flag` in mono text. |
| Read | Pull |
| Read/Write | Pull, push |
| Admin | All of the above, plus update description, create, and delete |
```
The alignment of the cells in the source doesn't really matter. The ending pipe
character is optional (unless the last cell is supposed to be empty).
### Feature-support table
```md
| Platform | x86_64 / amd64 |
| :--------- | :------------: |
| Ubuntu | ✅ |
| Debian | ✅ |
| Fedora | |
| Arch (btw) | ✅ |
```

99
content/contribute/components/tabs.md
View File

@@ -1,99 +0,0 @@
---
description: components and formatting examples used in Docker's docs
title: Tabs
toc_max: 3
---
The tabs component consists of two shortcodes:
- `{{</* tabs */>}}`
- `{{</* tab name="name of the tab" */>}}`
The `{{</* tabs */>}}` shortcode is a parent, component, wrapping a number of `tabs`.
Each `{{</* tab */>}}` is given a name using the `name` attribute.
You can optionally specify a `group` attribute for the `tabs` wrapper to indicate
that a tab section should belong to a group of tabs. See [Groups](#groups).
## Example
{{< tabs >}}
{{< tab name="JavaScript">}}
```js
console.log("hello world")
```
{{< /tab >}}
{{< tab name="Go">}}
```go
fmt.Println("hello world")
```
{{< /tab >}}
{{< /tabs >}}
## Markup
````markdown
{{</* tabs */>}}
{{</* tab name="JavaScript" */>}}
```js
console.log("hello world")
```
{{</* /tab */>}}
{{</* tab name="Go" */>}}
```go
fmt.Println("hello world")
```
{{</* /tab */>}}
{{</* /tabs */>}}
````
## Groups
You can optionally specify a tab group on the `tabs` shortcode.
Doing so will synchronize the tab selection for all of the tabs that belong to the same group.
### Tab group example
The following example shows two tab sections belonging to the same group.
{{< tabs group="code" >}}
{{< tab name="JavaScript">}}
```js
console.log("hello world")
```
{{< /tab >}}
{{< tab name="Go">}}
```go
fmt.Println("hello world")
```
{{< /tab >}}
{{< /tabs >}}
{{< tabs group="code" >}}
{{< tab name="JavaScript">}}
```js
const res = await fetch("/users/1")
```
{{< /tab >}}
{{< tab name="Go">}}
```go
resp, err := http.Get("/users/1")
```
{{< /tab >}}
{{< /tabs >}}

66
content/contribute/components/videos.md
View File

@@ -1,66 +0,0 @@
---
description: Learn about guidelines and best practices for videos in docs, and how to add a video component.
title: Videos
toc_max: 3
---
## Video guidelines
Videos are used rarely in Docker's documentation. When used, video should complement written text and not be the sole format of documentation. Videos can take longer to produce and be more difficult to maintain than written text or even screenshots, so consider the following before adding video:
- Can you demonstrate a clear customer need for using video?
- Does the video offer new content, rather than directly reading or re-purposing official documentation?
- If the video contains user interfaces that may change regularly, do you have a maintenance plan to keep the video fresh?
- Does the [voice and tone](../style/voice-tone.md) of the video align with the rest of the documentation?
- Have you considered other options, such as screenshots or clarifying existing documentation?
- Is the quality of the video similar to the rest of Docker's documentation?
- Can the video be linked or embedded from the site?
If all of the above criteria are met, you can reference the following best practices before creating a video to add to Docker documentation.
### Best practices
- Determine the audience for your video. Will the video be a broad overview for beginners, or will it be a deep dive into a technical process designed for an advanced user?
- Videos should be less than 5 minutes long. Keep in mind how long the video needs to be to properly explain the topic, and if the video needs to be longer than 5 minutes, consider text, diagrams, or screenshots instead. These are easier for a user to scan for relevant information.
- Videos should adhere to the same standards for accessibility as the rest of the documentation.
- Ensure the quality of your video by writing a script (if there's narration), making sure multiple browsers and URLs aren't visible, blurring or cropping out any sensitive information, and using smooth transitions between different browsers or screens.
Videos are not hosted in the Docker documentation repository. To add a video, you can [link to](./links.md) hosted content, or embed using an [iframe](#iframe).
## iframe
To embed a video on a docs page, use an `<iframe>` element:
```html
<iframe
class="border-0 w-full aspect-video mb-8"
allow="fullscreen"
title=""
src=""
></iframe>
```
## asciinema
`asciinema` is a command line tool for recording terminal sessions. The
recordings can be embedded on the documentation site. These are similar to
`console` code blocks, but since they're playable and scrubbable videos, they
add another level of usefulness over static codeblocks in some cases. Text in
an `asciinema` "video" can also be copied, which makes them more useful.
Consider using an `asciinema` recording if:
- The input/output of the terminal commands are too long for a static example
(you could also consider truncating the output)
- The steps you want to show are easily demonstrated in a few commands
- Where the it's useful to see both inputs and outputs of commands
To create an `asciinema` recording and add it to docs:
1. [Install](https://docs.asciinema.org/getting-started/) the `asciinema` CLI
2. Run `asciinema auth` to configure your client and create an account
3. Start a new recording with `asciinema rec`
4. Run the commands for your demo and stop the recording with `<C-d>` or `exit`
5. Upload the recording to <asciinema.org>
6. Embed the player with a `<script>` tag using the **Share** button on <asciinema.org>

82
content/contribute/file-conventions.md
View File

@@ -1,82 +0,0 @@
---
title: Source file conventions
description: How new .md files should be formatted
keywords: source file, contribute, style guide
weight: 30
---
## File name
When you create a new .md file for new content, make sure:
- File names are as short as possible
- Try to keep the file name to one word or two words
- Use a dash to separate words. For example:
- `add-seats.md` and `remove-seats.md`.
- `multiplatform-images` preferred to `multi-platform-images`.
## Front matter
The front matter of a given page is in a section at the top of the Markdown
file that starts and ends with three hyphens. It includes YAML content. The
following keys are supported. The title, description, and keywords are required.
| Key | Required | Description |
|-----------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| title | yes | The page title. This is added to the HTML output as a `<h1>` level header. |
| description | yes | A sentence that describes the page contents. This is added to the HTML metadata. It’s not rendered on the page. |
| keywords | yes | A comma-separated list of keywords. These are added to the HTML metadata. |
| aliases | no | A YAML list of pages which should redirect to the current page. At build time, each page listed here is created as an HTML stub containing a 302 redirect to this page. |
| notoc | no | Either `true` or `false`. If `true`, no in-page TOC is generated for the HTML output of this page. Defaults to `false`. Appropriate for some landing pages that have no in-page headings. |
| toc_min | no | Ignored if `notoc` is set to `true`. The minimum heading level included in the in-page TOC. Defaults to `2`, to show `<h2>` headings as the minimum. |
| toc_max | no | Ignored if `notoc` is set to `false`. The maximum heading level included in the in-page TOC. Defaults to `3`, to show `<h3>` headings. Set to the same as `toc_min` to only show `toc_min` level of headings. |
| sitemap | no | Exclude the page from indexing by search engines. When set to `false`, the page is excluded from `sitemap.xml`, and a `<meta name="robots" content="noindex"/>` header is added to the page. |
| sidebar.reverse | no | This parameter for section pages changes the sort order of the pages in that section. Pages that would normally appear at the top, by weight or by title, will instead appear near the bottom, and vice versa. |
| sidebar.goto | no | Set this to change the URL that the sidebar should point to for this entry. See [pageless sidebar entries](#pageless-sidebar-entries). |
| sidebar.badge | no | Set this to add a badge to the sidebar entry for this page. This param option consists of two fields: `badge.text` and `badge.color`. |
Here's an example of a valid (but contrived) page metadata. The order of
the metadata elements in the front matter isn't important.
```text
---
description: Instructions for installing Docker Engine on Ubuntu
keywords: requirements, apt, installation, ubuntu, install, uninstall, upgrade, update
title: Install Docker Engine on Ubuntu
aliases:
- /ee/docker-ee/ubuntu/
- /engine/installation/linux/docker-ce/ubuntu/
- /engine/installation/linux/docker-ee/ubuntu/
- /engine/installation/linux/ubuntu/
- /engine/installation/linux/ubuntulinux/
- /engine/installation/ubuntulinux/
- /install/linux/docker-ce/ubuntu/
- /install/linux/docker-ee/ubuntu/
- /install/linux/ubuntu/
- /installation/ubuntulinux/
toc_max: 4
---
```
## Body
The body of the page (with the exception of keywords) starts after the front matter.
### Text length
Splitting long lines (preferably up to 80 characters) can make it easier to provide feedback on small chunks of text.
## Pageless sidebar entries
If you want to add an entry to the sidebar, but you want the link to point somewhere else, you can use the `sidebar.goto` parameter.
This is useful in combination with `build.render` set to `always`, which creates a pageless entry in the sidebar that links to another page.
```text
---
title: Dummy sidebar link
build:
render: never
sidebar:
goto: /some/other/page/
weight: 30
---
```

257
content/contribute/guides.md
View File

@@ -1,257 +0,0 @@
---
title: Guidelines for writing Docker usage guides
linkTitle: Write a Docker guide
description: Learn how to write guides for learning about Docker, with Docker.
---
<!-- vale Docker.We = NO -->
This guide provides instructions and best practices for writing tutorial-style
usage guides that help users achieve specific goals using Docker. These guides
will be featured in the [guides section](/guides/_index.md) of the website,
alongside our product manuals and reference materials.
Our documentation is written in Markdown, with YAML front matter for metadata.
We use [Hugo](https://gohugo.io) to build the website. For more information
about how to write content for Docker docs, refer to our
[CONTRIBUTING.md](https://github.com/docker/docs/tree/main/CONTRIBUTING.md).
## Purpose of the guides
Our usage guides aim to:
- Educate users on how to leverage Docker in various contexts.
- Provide practical, hands-on experience through step-by-step tutorials.
- Help users achieve specific goals relevant to their interests or projects.
## Audience
- Experience levels: From beginners to advanced users.
- Roles: Developers, system administrators, DevOps engineers, and more.
- Technologies: Various programming languages and frameworks.
## Metadata for guides
Each guide must include a metadata section at the beginning of the document.
This metadata helps users discover and filter guides based on their interests
and needs.
### Example metadata format
```yaml
---
title: Deploy a machine learning model with Docker
linkTitle: Docker for ML deployment
description: Learn how to containerize and deploy a machine learning model using Docker.
summary: |
This guide walks you through the steps to containerize a machine learning
model and deploy it using Docker, enabling scalable and portable AI
solutions.
tags: [machine-learning, deployment]
languages: [python]
params:
time: 30 minutes
---
```
### Metadata fields
- `title` (required): The main title of the guide in sentence case.
- `linkTitle` (optional): A shorter title used in navigation menus.
- `description` (required): A concise description for SEO purposes.
- `summary` (required): A brief overview of the guide's content.
- `languages` \* (optional): List of programming languages used.
- `tags` \* (optional): Domains or subject areas covered.
- `params`
- `time` (optional): Estimated reading or completion time.
\* Do apply at least one of the `languages` or `tags` taxonomies. The values
are used to associate the page with the filter options on the guides landing
page.
## Document structure
Our guides emphasize learning by doing. Depending on the type of guide, the
structure may vary to best suit the content and provide a smooth learning
experience.
All guides live directly under the `content/guides/` directory in the Docker
docs repository. Guides can either be a single page or multiple pages. In the
case of multi-page guides, every page is a step in a sequential workflow.
If you're creating a single-page guide, create a single markdown file in the
guides directory:
```bash
# Create the file
touch content/guides/my-docker-guide.md
# or if you have Hugo installed:
hugo new content/guides/my-docker-guide.md
```
To create a multi-page guide, create a directory where each page is a markdown
file, with an `_index.md` file representing the introduction to the guide.
```bash
# Create the index page for the guide
mkdir content/guides/my-docker-guide.md
touch content/guides/my-docker-guide/_index.md
# or if you have Hugo installed:
hugo new content/guides/my-docker-guide/_index.md
```
Then create the pages for the guide under `content/guides/<dir>/<page>.md` as
needed. The [metadata](#metadata-for-guides) lives on the `_index.md` page (you
don't need to assign metadata to individual pages).
### Guides for specific frameworks or languages
For guides that demonstrate how to use Docker with a particular framework or
programming language, consider the following outline:
1. **Introduction**
- Briefly introduce the framework or language in the context of Docker.
- Explain what the user will achieve by the end of the guide.
- List required software, tools, and knowledge.
2. **Development setup**
- Guide the user through setting up a development environment.
- Include instructions on writing or obtaining sample code.
- Show how to run containers for local development.
3. **Building the application**
- Explain how to create a Dockerfile tailored to the application.
- Provide step-by-step instructions for building the Docker image.
- If applicable, show how to test the application using Docker.
4. **Deploying with Docker**
- Show how to run the application in a Docker container.
- Discuss configuration options and best practices.
5. **Best practices and conclusions**
- Offer tips for optimizing Docker usage with the framework or language.
- Summarize key takeaways, suggest next steps, and further reading.
### Use-case guides
For guides focused on accomplishing a specific goal or use case with Docker
(e.g., deploying a machine learning model), use a flexible outline that ensures
a logical flow.
The following outline is an example. The structure should be adjusted to best
fit the content and ensure a clear, logical progression. Depending on the
subject matter of your use-case guide, the exact structure will vary.
1. **Introduction**
- Describe the problem or goal.
- Explain the benefits of using Docker in this context.
2. **Prerequisites**
- List required tools, technologies, and prior knowledge.
3. **Setup**
- Provide instructions for setting up the environment.
- Include any necessary configuration steps.
4. **Implementation**
- Walk through the process step by step.
- Use code snippets and explanations to illustrate key points.
5. **Running or deploying the application**
- Guide the user on how to execute or deploy the solution.
- Discuss any verification steps to ensure success.
6. **Conclusion**
- Recap what was achieved.
- Suggest further reading or advanced topics.
## Example code
If you create an example repository with source code to accompany your guide,
we strongly encourage you to publish that repository under the
[dockersamples](https://github.com/dockersamples) organization on GitHub.
Publishing your source code under this organization, rather than your personal
account, ensures that the source code remains accessible to the maintainers of
the documentation site after publishing. In the event of a bug or an issue in
the guide, the documentation team can more easily update the guide and its
corresponding example repository.
Hosting the examples in the official samples namespace also helps secure trust
with users who are reading the guide.
### Publish a repository under `dockersamples`
To publish your repository under the `dockersamples` organization, use the
[dockersamples template](https://github.com/dockersamples/sample-app-template)
to initiate a sample repository under your personal namespace. When you've
finished drafting your content and opened your pull request for the
documentation, we can transfer the repository to the dockersamples
organization.
## Writing style
Use [sentence case](/contribute/style/formatting.md#capitalization) for all
headings and titles. This means only the first word and proper nouns are
capitalized.
### Voice and tone
- **Clarity and conciseness**: Use simple language and short sentences to convey information effectively.
- **Active voice**: Write in the active voice to engage the reader (e.g., "Run the command" instead of "The command should be run").
- **Consistency**: Maintain a consistent tone and terminology throughout the guide.
For detailed guidelines, refer to our [voice and tone documentation](/contribute/style/voice-tone.md).
### Formatting conventions
- **Headings**: Use H2 for main sections and H3 for subsections, following sentence case.
- **Code examples**: Provide complete, working code snippets with syntax highlighting.
- **Lists and steps**: Use numbered lists for sequential steps and bullet points for non-sequential information.
- **Emphasis**: Use bold for UI elements (e.g., **Button**), and italics for emphasis.
- **Links**: Use descriptive link text (e.g., [Install Docker](/get-started/get-docker.md)).
For more details, see our [content formatting guidelines](/contribute/style/formatting.md)
and [grammar and style rules](/contribute/style/grammar.md).
## Best practices
- **Test all instructions**
- Ensure all code and commands work as expected.
- Verify that the guide can be followed successfully from start to finish.
- **Relevance**
- Focus on real-world applications and scenarios.
- Keep the content up-to-date with the latest Docker versions.
- **Troubleshooting tips**
- Anticipate common issues and provide solutions or references.
- **Visual aids**
- Include screenshots or diagrams where they enhance understanding.
- Add captions and alt text for accessibility.
- **Third-party tools**
- Avoid requiring the user to install third-party tools or modify their local development environment.
- Prefer using containerized tools and methods where applicable (e.g. `docker exec`).
- Some tools are reasonable to assume as installed or prerequisites for guides, such as Node.js and npm. Use your better judgement.
## Additional resources
- **Existing guides**
- Refer to [Docker Guides](/guides/_index.md) for examples and inspiration.
- **Style guides**
- [Voice and tone](/contribute/style/voice-tone.md)
- [Content formatting](/contribute/style/formatting.md)
- [Grammar and style](/contribute/style/grammar.md)
## Submission process
- **Proposal**
- Raise an issue on the [Docker documentation GitHub repository](https://github.com/docker/docs)
with a request to add a new guide.
- Once the proposal has been accepted, start writing your guide by forking
the repository and creating a branch for your work.
> [!NOTE]
> Avoid contributing from the `main` branch of your fork, since it makes it
> more difficult for maintainers to help you fix any issues that may arise.
- **Review**
- Proofread your guide for grammar, clarity, and adherence to the guidelines.
- Once your draft is ready, raise a pull request, with a reference to the
original issue.
- The Docker documentation team and subject matter experts will review your
submission and provide feedback on the pull request directly.
- **Publishing**
- Your guide will be published on the Docker documentation website when the
reviewers have approved and merged your pull request.
Thank you for contributing to the Docker community. Your expertise helps users
worldwide harness the power of Docker.

6
content/contribute/style/_index.md
View File

@@ -1,6 +0,0 @@
---
build:
render: never
title: Style guide
weight: 20
---

177
content/contribute/style/formatting.md
View File

@@ -1,177 +0,0 @@
---
title: Formatting guide
description: Formatting guidelines for technical documentation
keywords: formatting, style guide, contribute
toc_max: 2
weight: 20
---
## Headings and subheadings
Readers pay fractionally more attention to headings, bulleted lists, and links, so it's important to ensure the first two to three words in those items "front load" information as much as possible.
### Best practice
- Headings and subheadings should let the reader know what they will find on the page.
- They should describe succinctly and accurately what the content is about.
- Headings should be short (no more than eight words), to the point and written in plain, active language.
- You should avoid puns, teasers, and cultural references.
- Skip leading articles (a, the, etc.)
## Page title
Page titles should be action orientated. For example: - _Enable SCIM_ - _Install Docker Desktop_
### Best practice
- Make sure the title of your page and the table of contents (TOC) entry matches.
- If you want to use a ‘:’ in a page title in the table of contents (\_toc.yaml), you must wrap the entire title in “” to avoid breaking the build.
- If you add a new entry to the TOC file, make sure it ends in a trailing slash (/). If you don't, the page won't show the side navigation.
## Images
Images, including screenshots, can help a reader better understand a concept. However, you should use them sparingly as they tend to go out-of-date.
### Best practice
- When you take screenshots:
- Don’t use lorem ipsum text. Try to replicate how someone would use the feature in a real-world scenario, and use realistic text.
- Capture only the relevant UI. Don’t include unnecessary white space or areas of the UI that don’t help illustrate the point.
- Keep it small. If you don’t need to show the full width of the screen, don’t.
- Review how the image renders on the page. Make sure the image isn’t blurry or overwhelming.
- Be consistent. Coordinate screenshots with the other screenshots already on a documentation page for a consistent reading experience.
- To keep the Git repository light, compress the images (losslessly). Be sure to compress the images before adding them to the repository. Compressing images after adding them to the repository actually worsens the impact on the Git repository (however, it still optimizes the bandwidth during browsing).
- Don't forget to remove images from the repository that are no longer used.
For information on how to add images to your content, see [Useful component and formatting examples](../components/images.md).
## Links
Be careful not to create too many links, especially within body copy. Excess links can be distracting or send readers away from the current page.
When people follow links, they can often lose their train of thought and fail to return to the original page, despite not having absorbed all the information it contains.
The best links offer readers another way to scan information.
### Best practice
- Use plain language that doesn't mislead or promise too much.
- Be short and descriptive (around five words is best).
- Allow people to predict (with a fair degree of confidence) what they will get if they select a link. Mirror the heading text on the destination page in links whenever possible.
- Front-load user-and-action-oriented terms at the beginning of the link (Download our app).
- Avoid generic calls to action (such as click here, find out more).
- Don't include any end punctuation when you hyperlink text (for example, periods, question marks, or exclamation points).
- Don't make link text italics or bold, unless it would be so as normal body copy.
For information on how to add links to your content, see [Useful component and formatting examples](../components/links.md).
## Code and code samples
Format the following as code: Docker commands, instructions, and filenames (package names).
To apply inline code style, wrap the text in a single backtick (`).
For information on how to add code blocks to your content, see [Useful component and formatting examples](../components/code-blocks.md).
### Best practice for commands
- Command prompt and shell:
- For a non-privileged shell, prefix commands in code blocks with the $ prompt symbol.
- For a privileged shell, prefix commands in code blocks with the # prompt symbol.
- For a remote shell, add the context of the remote machine and exclude the path. For example, `user@host $`.
- Specify the Windows shell (Command Prompt, PowerShell, or Git Bash), when you add any Windows-specific command. It's not necessary to include a command for each Windows shell.
- Use tabs when you add commands for multiple operating systems or shells. For information on how to add tabs to your content, see [Tabs](../components/tabs.md).
- Commands that users will copy and run:
- Add a single command per code block if a command produces output or requires the user to verify the results.
- Add command output to a separate code block from the command.
- Commands that users won't copy and run:
- Use POSIX-compatible syntax. It's not necessary to include Windows syntax.
- Wrap optional arguments in square brackets ( [ ] ).
- Use pipes ( \| ) between mutually exclusive arguments.
- Use three dots ( ... ) after repeated arguments.
### Best practice for code
- Indent code blocks by 3 spaces when you nest a code block under a list item.
- Use three dots ( ... ) when you omit code.
## Callouts
Use callouts to emphasize selected information on a page.
### Best practice
- Format the word Warning, Important, or Note in bold. Don't bold the content within the callout.
- It's good practice to avoid placing a lot of text callouts on one page. They can create a cluttered appearance if used to excess, and you'll diminish their impact.
| Text callout | Use case scenario | Color or callout box |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| Warning | Use a Warning tag to signal to the reader where actions may cause damage to hardware or software loss of data. | Red |
| | ✅ Example: Warning: When you use the docker login command, your credentials are stored in your home directory in .docker/config.json. The password is base64-encoded in this file. | |
| Important | Use an Important tag to signal to the reader where actions may cause issues of a lower magnitude. | Yellow |
| | ✅ Example: Update to the Docker Desktop terms | |
| Note | Use the Note tag for information that may not apply to all readers, or if the information is tangential to a topic. | Blue |
| | ✅ Example: Deleting a repository deletes all the images it contains and its build settings. This action cannot be undone. | |
For information on how to add callouts to your content, see [Useful component and formatting examples](../components/call-outs.md).
## Navigation
When documenting how to navigate through the Docker Desktop or Docker Hub UI:
- Always use location, then action. For example:
_From the **Visibility** drop-down list (location), select Public (action)._
- Be brief and specific. For example:
Do: _Select **Save**._
Don't: _Select **Save** for the changes to take effect._
- If a step must include a reason, start the step with it. This helps the user scan more quickly.
Do: _To view the changes, in the merge request, select the link._
Don't: _Select the link in the merge request to view the changes_
## Optional steps
If a step is optional, start the step with the word Optional followed by a period.
For example:
_1. Optional. Enter a description for the job._
## Placeholder text
You might want to provide a command or configuration that uses specific values.
In these cases, use < and > to call out where a reader must replace text with their own value. For example:
`docker extension install <name-of-your-extension>`
## Tables
Use tables to describe complex information in a straightforward manner.
Note that in many cases, an unordered list is enough to describe a list of items with a single, simple description per item. But, if you have data that’s best described by a matrix, tables are the best choice.
### Best practice
- Use sentence case for table headings.
- To keep tables accessible and scannable, tables shouldn't have any empty cells. If there is no otherwise meaningful value for a cell, consider entering N/A for ‘not applicable’ or None.
For information on how to add tables to your content, see [Useful component and formatting examples](../components/tables.md).
## Referring to file types
When you're discussing a file type, use the formal name of the type. Don't use the filename extension to refer generically to the file type.
| Correct | Incorrect |
| --- | --- |
| a PNG file | a .png file |
| a Bash file | an .sh file |
## Referring to units
When you're referring to units of measurement, use the abbreviated form in all caps, with a space between the value and the unit. For example:
| Correct | Incorrect |
| --- | --- |
| 10 GB | 10GB |
| 10 GB | 10 gb |
| 10 GB | 10 gigabytes |

175
content/contribute/style/grammar.md
View File

@@ -1,175 +0,0 @@
---
title: Grammar and style
description: Grammar and style guidelines for technical documentation
keywords: grammar, style, contribute
toc_max: 2
weight: 10
---
Docker documentation should always be written in US English with US grammar.
## Acronyms and initialisms
An acronym is an abbreviation you would speak as a word, for example, ROM (for read only memory). Other examples include radar and scuba, which started out as acronyms but are now considered words in their own right.
An initialism is a type of acronym that comprises a group of initial letters used as an abbreviation for a name or expression. If you were using the acronym in a spoken conversation, you would enunciate each letter: H-T-M-L for Hypertext Markup Language.
### Best practice
- Spell out lesser-known acronyms or initialisms on first use, then follow with the acronym or initialism in parentheses. After this, throughout the rest of your page or document, use the acronym or initialism alone.
> ‘You can use single sign-on (SSO) to sign in to Notion. You may need to ask your administrator to enable SSO.’
- Where the acronym or initialism is more commonly used than the full phrase, for example, URL, HTML, you don't need to follow this spell-it-out rule.
- Use all caps for acronyms of file types (a JPEG file).
- Don't use apostrophes for plural acronyms. ✅URLs ❌URL’S
- Avoid using an acronym for the first time in a title or heading. If the first use of the acronym is in a title or heading, introduce the acronym (in parentheses, following the spelled-out term) in the first body text that follows.
## Bold and italics
Unless you're referring to UI text or user-defined text, you shouldn't add emphasis to text. Clear, front-loaded wording makes the subject of a sentence clear.
### Best practice
- Don't use bold to refer to a feature name.
- Use italics sparingly, as this type of formatting can be difficult to read in digital experiences.
Notable exceptions are titles of articles, blog posts, or specification documents.
## Capitalization
Use sentence case for just about everything. Sentence case means capitalizing only the first word, as you would in a standard sentence.
The following content elements should use sentence case:
- Titles of webinars and events
- Headings and subheadings in all content types
- Calls to action
- Headers in boxed text
- Column and row headers in tables
- Links
- Sentences (of course)
- Anything in the UI including navigation labels, buttons, headings
### Best practice
- As a general rule, it's best to avoid the use of ALL CAPITALS in most content types. They are more difficult to scan and take up more space. While all caps can convey emphasis, they can also give the impression of shouting.
- If a company name is all lowercase or all uppercase letters, follow their style, even at the beginning of sentences: DISH and bluecrux. When in doubt, check the company's website.
- Use title case for Docker solutions: Docker Extensions, Docker Hub.
- Capitalize a job title if it immediately precedes a name (Chief Executive Officer Scott Johnston).
- Don't capitalize a job title that follows a name or is a generic reference (Scott Johnston, chief executive officer of Docker).
- Capitalize department names when you refer to the name of a department, but use lower case if you are talking about the field of work and not the actual department.
- When referring to specific user interface text, like a button label or menu item, use the same capitalization that’s displayed in the user interface.
## Contractions
A contraction results from letters being left out from the original word or phrase, such as you're for you are or it's for it is.
Following our conversational approach, it's acceptable to use contractions in almost all content types. Just don't get carried away. Too many contractions in a sentence can make it difficult to read.
### Best practice
- Stay consistent - don't switch between contractions and their spelled-out equivalents in body copy or UI text.
- Avoid negative contractions (can't, don't, wouldn't, and shouldn't) whenever possible. Try to rewrite your sentence to align with our helpful approach that puts the focus on solutions, not problems.
- Never contract a noun with is, does, has, or was as this can make it look like the noun is possessive. Your container is ready. Your container’s ready.
## Dangling modifiers
Avoid [dangling modifiers](https://en.wikipedia.org/wiki/Dangling_modifier), where the subject of a clause's verb is unclear:
- ❌ After enabling auto-log-out, your users are logged out.
- ✅ When you enable auto-log-out, your users are logged out.
## Dates
You should use the U.S. format of month day, year format for dates: June 26, 2021.
When possible, use the month's full name (October 1, 2022). If there are space constraints, use 3-letter abbreviations followed by a period (Oct. 1. 2022).
## Decimals and fractions
In all UI content and technical documentation, use decimals instead of fractions.
### Best practice
- Always carry decimals to at least the hundredth place (33.76).
- In tables, align decimals on the decimal point.
- Add a zero before the decimal point for decimal fractions less than one (0.5 cm).
## Lists
Lists are a great way to break down complex ideas and make them easier to read and scan.
### Best practice
- Bulleted lists should contain relatively few words or short phrases. For most content types, limit the number of items in a list to five.
- Don’t add commas (,) or semicolons (;) to the ends of list items.
- Some content types may use bulleted lists that contain 10 items, but it's preferable to break longer lists into several lists, each with its own subheading or introduction.
- Never create a bulleted list with only one bullet, and never use a dash to indicate a bulleted list.
- If your list items are fragments, capitalize the list items for ease of scanning but don't use terminal punctuation.
Example:
I went to the shops to buy:
- Milk
- Flour
- Eggs
- Make sure all your list items are parallel. This means you should structure each list item in the same way. They should all be fragments, or they should all be complete sentences. If you start one list item with a verb, then start every list item with a verb.
- Every item in your list should start with a capital letter unless they’re parameters or commands.
- Nested sequential lists are labeled with lowercase letters. For example:
1. Top level
2. Top level
1. Child step
2. Child step
## Numbers
When you work with numbers in content, the best practices include:
- Spell out the numbers one to nine, except in units of measure such as 4 MB.
- Represent numbers with two or more digits as numerals (10, 625, 773,925).
- Recast a sentence, rather than begin it with a number (unless it's a year).
- When you cite numbers in an example, write them out as they appear in any accompanying screenshots.
- Write numbers out as they appear on the platform when you cite them in an example.
- To refer to large numbers in abstract (such as thousands, millions, and billions), use a combination of words and numbers. Don't abbreviate numeric signifiers.
- Avoid using commas in numbers because they can represent decimals in different cultures. For numbers that are five digits or more, use a space to separate.
| Correct | Incorrect |
| --- | --- |
| 1000 | 1,000 |
| 14 586 | 14,586 |
| 1 390 680 | 1,390,680 |
### Versions
When writing version numbers for release notes, use the following example:
- version 4.8.2
- v1.0
- Docker Hub API v2
## Punctuation
### Colons and semicolons
- Use colons to: introduce a list inline in a sentence; introduce a bulleted or numbered list; and provide an explanation.
- Don't use semicolons. Use two sentences instead.
### Commas
- Use the serial or Oxford comma - a comma before the coordinating conjunction (and, or) in a list of three or more things.
- If a series contains more than three items or the items are long, consider a bulleted list to improve readability.
### Dashes and hyphens
- Use the em dash (-) sparingly when you want the reader to pause, to create parenthetical statements, or to emphasize specific words or phrases. Always put a space on either side of the em dash.
- Use an en dash (-) to indicate spans of numbers, dates, or time.
- Use a hyphen to join two or more words to form compound adjectives that precede a noun. The purpose of joining words to form a compound adjective is to differentiate the meaning from the adjectives used separately (for example, ‘up-to-date documentation’ ‘lump-sum payment’, and ‘well-stocked cupboard’. You can also use a hyphen to:
- Avoid awkward doubling of vowels. For example ‘semi-independence*’,* or ‘re-elect’.
- Prevent misreading of certain words. For example ‘Re-collect’ means to collect again; without a hyphen the word recollect has a different meaning.
### Exclamation marks
Avoid the use of exclamation marks.
### Parentheses
Don't use parentheses in technical documentation. They can reduce the readability of a sentence.

182
content/contribute/style/recommended-words.md
View File

@@ -1,182 +0,0 @@
---
title: Recommended word list
description: Recommended word list for Technical documentation
keywords: recommended word list, style guide, contribute
weight: 30
---
To help ensure consistency across documentation, the Technical Writing team recommends these wording choices.
#### & (ampersand)
Don't use `&` instead of `and` in headings, text, navigation, UI copy, or tables of contents.
#### above
Try to avoid using `above` when referring to an example or table in a documentation page. If required, use `previous` instead.
For example:
_In the previous example, the dog had fleas._
#### account name
Don't use. Instead, use `username`.
#### admin
Write out `administrator` on first use. Use `admin` if it's the name of a UI label or other element.
#### allows
Don't use. Instead, use `lets`.
#### as of this writing
Avoid because the writing itself implies this phrase. The phrase can also prematurely share product or feature strategy or inappropriately imply that a product or feature might change.
#### below
Try to avoid `below` when referring to an example or table on a documentation page. If required, use `following` instead.
For example:
_In the following example, the dog had fleas._
#### checkbox
Use one word for `checkbox`. Don't use `check box`.
You select (not check or enable) and clear (not deselect or disable) checkboxes.
#### click
Don't use `click`. Instead, use `select` with buttons, links, menu items, and lists.
Select applies to more devices, while click is more specific to a mouse.
#### currently
Don't use `currently` when talking about the product or its features. The documentation describes the product as it is today.
#### disable
Don't use `disable`. Implies that disability is a less-desired or negative state.
Instead, use `turn off` or `toggle off`.
There are times with more technical features when the development team uses `disable`, and in these cases, it's OK to use the term.
#### earlier
Use `earlier` when talking about version numbers.
Use:
_In Docker Desktop 4.1 and earlier._
Instead of:
_In Docker Desktop 4.1 and lower._
#### easy, easily
What might be easy for you might not be easy for others. Try eliminating this word from the sentence because usually the same meaning can be conveyed without it.
<!-- markdownlint-disable no-trailing-punctuation -->
#### e.g.
<!-- markdownlint-enable no-trailing-punctuation -->
Don't use. Instead, use phrases like `for example` or `such as`.
#### enable
Don't use `enable`. Implies that disability is a less-desired or negative state.
Instead, use `turn on` or `toggle on`.
There are times with more technical features when the development team uses `enable`, and in these cases, it's OK to use the term.
#### execute
Avoid where possible. Use `run` instead.
#### later
Use `later` when talking about version numbers.
Use:
_In Docker Desktop 4.1 and later._
Instead of:
_In Docker Desktop 4.1 and higher…_ or _In Docker Desktop 4.1 and above…_
#### please
Don't use `please` in the normal course of explaining how to use a product, even if you're explaining a difficult task. Also don't use the phrase `please note`.
#### register
Use `sign up` instead of register when talking about creating an account.
#### repo
Don't use. Instead, use `repository`.
#### respectively
Avoid `respectively` and be more precise instead.
#### scroll
Avoid. Use a verb phrase such as _move through_ or _navigate to_ instead, if the context is clear.
#### sign in
Use `sign in` instead of `sign on`, `signon`, `log on`, `logon`, or `log in`, `login`. If the user interface uses different words, use those.
Use `sign in to` instead of `sign into`.
#### sign up
Use `sign up` or `create account` instead of `register` when talking about creating an account.
#### tab versus view
Use `view` when referring to a major section in a UI. Use `tab` when referring to a sub-section in the UI.
For example, in Docker Desktop, the **Images** view and the **Local** tab.
#### toggle
You turn on or turn off a toggle. For example:
_Turn on the dark mode toggle._
#### upgrade
Use `upgrade` when describing a higher subscription tier
#### vs
Don't use `vs` or `vs.` as an abbreviation for versus; instead, use the unabbreviated `versus`.
#### we
Try to avoid `we` and focus instead on how the user can carry out something in Docker.
Use:
_Use widgets when you have work you want to organize._
Instead of:
_We created a feature for you to add widgets._
#### wish
Don't use. Use `want` instead.

63
content/contribute/style/terminology.md
View File

@@ -1,63 +0,0 @@
---
title: Docker terminology
description: Docker specific terminology and definitions
keywords: terminology, style guide, contribute
---
#### `compose.yaml`
The current designation for the Compose file, as it's a file, format as code.
#### Compose plugin
The compose plugin as an add-on (for Docker CLI) that can be enabled/disabled.
#### Digest
A long string that’s automatically created every time you push an image. You can pull an image by Digest or by Tag.
#### Docker Compose
Use when we talk about the application, or all the functionality associated with the application.
#### `docker compose`
Use code formatting for referring to the commands in text and command usage examples/code samples.
#### Docker Compose CLI
Use when referring to family of Compose commands as offered from the Docker CLI.
#### K8s
Don't use. Use `Kubernetes` instead.
#### Multi-platform
(broad meaning) Mac vs Linux vs Microsoft but also pair of platform architecture such as in Linux/amd64 and Linux/arm64; (narrow meaning) Windows/Linux/macOS.
#### Multi-architecture / multi-arch
To use when referring specifically to CPU architecture or something that is hardware-architecture-based. Avoid using it as meaning the same as multi-platform.
#### Member
A user of Docker Hub that is a part of an organization
#### Namespace
Organization or User name. Every image needs a namespace to live under.
#### Node
A node is a physical or virtual machine running an instance of the Docker Engine in swarm mode.
Manager nodes perform swarm management and orchestration duties. By default manager nodes are also worker nodes.
Worker nodes invoke tasks.
#### Registry
Online storage for Docker images.
#### Repository
Lets users share container images with their team, customers, or Docker community.

49
content/contribute/style/voice-tone.md
View File

@@ -1,49 +0,0 @@
---
title: Voice and tone
description: Docker's voice and tone
keywords: style guide, voice, tone, content standards
---
## Voice
At Docker, we've been the customer. We're developers developing for developers. We speak with experience and knowledge and without arrogance or ego. We want to inform and empower people without being confusing or pushy.
We're not afraid to use a bit of cheeky humor to lighten the conversation (and because we don't take ourselves too seriously) but we're always respectful. We communicate with clarity, empathy, and wit; everything we say should inform and encourage.
We align our tone of voice and content with our virtues. The most important principles we follow when we write are the 4Cs:
1. **Correct**
2. **Concise**
3. **Complete**
4. **Clear**
We ensure the information is accurate, succinct, thorough, and easy to understand. We keep sentences as simple as possible, but include enough detail for the user to complete the intended task.
All of this means that when we write documentation and UI copy:
1. **We are honest.** We give you all the facts and we don't use misdirection or make ambiguous statements. We don't always have all the answers, but we're doing our best to make life better for developers and we'll tell you how it's going.
2. **We are concise.** We understand the industry of complex and detailed messaging our users live in because we come from the same world. Docker doesn't bulk up our communication with fluffy words or complex metaphors. We're clear and to the point.
3. **We are relaxed.** Our demeanor is casual but not lazy, smart but not arrogant, and focused but not cold. Our voice should be welcoming and warm.
4. **We are inclusive.** Developers are developers no matter how much code they've written. Every person is as much a part of our community as the next. We are accepting of all developers from all industries and experience levels.
## Tone
Docker's tone is usually informal, but we believe it's always more important to be clear over comical. We're relaxed, but we're not inappropriate or unprofessional.
### Friendly tone
Use a tone that's natural, friendly, and respectful without being overly colloquial or full of jargon. Write to inform and empower developers without being confusing or pushy. It’s OK to use contractions as long as the sentence doesn’t become too slangy or informal.
**Avoid overdoing politeness.** It is good to be friendly and polite, but using ‘please’ in technical documentation or UI copy might be overdoing the politeness.
### Positive language
Use positive language. Instead of highlighting the limitations and what the users cannot do, emphasize the positive outcomes.
For 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*.”

73
content/contribute/ui.md
View File

@@ -1,73 +0,0 @@
---
title: UI elements in content
description: How to refer to and write about UI elements in technical documentation.
keywords: ui, contribute, style guide, docker docs
weight: 40
---
Use this guide when writing documentation that refers to buttons, fields, menus, dialogs, or other user interface (UI) elements. It explains how to format UI terms, write task-focused instructions, and refer to common UI patterns consistently and clearly.
## Format UI element names
Use bold formatting for the visible names of UI elements:
- Buttons
- Dialogs
- Windows
- Tabs
- Menu items
- List items
- Form labels
- Section headings
For example:
*Select **Create**, then fill out the **Name** field.*
Do not bold product names or features unless they appear exactly as a label in the UI.
### Capitalization
- Follow the capitalization as it appears in the UI.
- If UI labels are all uppercase or inconsistent, use sentence case in your docs for readability.
## Write task-focused instructions
When possible, guide users based on what they’re trying to do, not just what they should select. This makes docs more goal-oriented and adaptable to UI changes.
| Do this | Avoid this |
|----------------------------------|-------------------------------------------|
| Expand the **Advanced options** section. | Select the zippy to expand the **Advanced options** section. |
| Choose a base image for your container. | Select a dropdown and pick something. |
## Use correct prepositions with UI elements
Choose the right preposition based on the type of UI element you're referencing.
| Preposition | Use with... | Example |
|-------------|--------------------------------|---------|
| **in** | dialogs, fields, lists, menus, panes, windows | In the **Name** field, enter your project name. |
| **on** | pages, tabs, toolbars | On the **Settings** tab, select **General**. |
## Use consistent UI element terms
Use these standard terms when referring to elements in Docker products:
| Preferred Term | Use When Referring To... |
|---------------------|----------------------------------------------|
| **button** | A clickable action element (e.g., **Start**) |
| **field** | A place to enter text or select a value |
| **menu** / **menu item** | A drop-down or navigation option |
| **drop-down** | A drop-down menu item |
| **context switcher** | Specific to toggling on cloud mode |
| **tab** | A selectable view within a window or page |
| **dialog** | A popup window for confirmations or options |
| **section** | A logical grouping of content on a page |
| **list** / **list item** | A scrollable list of selectable entries |
| **toggle** | A binary control (on/off) |
| **checkbox** | A multi-select control |
| **tooltip** | Text that appears on hover |
Finally, instead of saying “click the control,” say “select the **Create** button.”

5
layouts/partials/footer.html
View File

@@ -44,11 +44,6 @@
class="inline-flex truncate whitespace-normal"
>About us</a
>
{{- with .GetPage "/contribute" }}
<a href="{{ .Permalink }}" class="inline-flex truncate whitespace-normal"
>{{ .LinkTitle }}</a
>
{{- end }}
<a
href="{{ "llms.txt" | relURL }}"
class="inline-flex truncate whitespace-normal"

BIN
static/assets/images/banner_image_24512.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 7.7 KiB

BIN
static/assets/images/footer_moby_icon.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 6.9 KiB

261
tech_writer.yml
View File

@@ -152,12 +152,17 @@ agents:
writer:
model: writer_sonnet
description: Technical writer for creating and editing Docker documentation
add_prompt_files:
- STYLE.md
- COMPONENTS.md
instruction: |
<objective>
Write technical documentation for Docker. Create clear, practical content
that helps users understand and use Docker effectively. Focus purely on
content quality - the editor will handle formatting, style polish, and
Hugo syntax.
that helps users understand and use Docker effectively.
STYLE.md provides the complete style guide. Follow it. COMPONENTS.md shows
how to use Hugo shortcodes and components. Your job is to create content -
the editor will polish formatting and validate.
</objective>
<context>
@@ -168,115 +173,49 @@ agents:
- Markdown with front matter
- Vendored content from upstream repos (read-only, don't edit)
The editor handles:
- Line wrapping and formatting
- Style polish (word choice, voice, tense)
- Hugo syntax validation
- Running prettier and validation tools
Division of labor:
- You: Create content, structure information, explain concepts
- Editor: Format, polish style, validate Hugo syntax, run checks
You focus on:
- What to say and how to structure it
- Clear explanations and practical guidance
- Examples that help users understand
Don't worry about perfect line wrapping, exact word choices, or Hugo
syntax details. Get the content right - the editor handles the rest.
</context>
<process>
1. If updating existing content, read it first
2. Understand the topic and what needs to be documented
3. Use filesystem tools (glob, grep, read) to find related content and
1. If updating existing content, read it first to understand scope and
character
2. Use filesystem tools (glob, grep, read) to find related content and
examples
4. Write clear, conversational content following the principles
5. Focus on content - the editor handles formatting, syntax, and style
6. When done, your work returns to the root agent
Write files directly. Don't just provide drafts.
3. Write clear, conversational content following STYLE.md principles
4. Include front matter (title, description, keywords minimum)
5. Use shortcodes and components from COMPONENTS.md as needed
6. Write files directly - don't just provide drafts
7. When done, return to root agent for editor handoff
</process>
<rules>
<voice>
Write like a knowledgeable colleague explaining something useful.
- Direct and practical: Get to the point quickly. Users are here to
solve problems.
- Conversational but professional: Use "you" and active voice. Avoid
corporate-speak.
- Confident without condescending: Assume the reader is capable.
- Specific over generic: Be clear about what users should do.
</voice>
<structure>
Every page should answer "What will I learn?" and "Why does this
matter?" within the first paragraph.
Connect ideas naturally. Each section should flow logically from the
previous one.
</structure>
<scope_preservation>
When updating existing documentation:
1. Understand the current document: Read it fully to grasp its scope,
length, and character. Is it a minimal how-to or a comprehensive
reference?
2. 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.
3. Add only what's genuinely missing: Fill gaps, don't elaborate. If
the document already covers a topic adequately, don't expand it.
4. Value brevity: Say what needs to be said, then stop. Users
appreciate conciseness. Not every topic needs prerequisites,
troubleshooting, best practices, and examples sections.
5. 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.
</scope_preservation>
- Read before editing: Always read existing files before modifying them
- Preserve scope: Match the existing document's length and character (see
STYLE.md "Scope preservation")
- Answer the key questions: Every page should answer "What will I learn?"
and "Why does this matter?" in the first paragraph
- Write, don't narrate: Execute without explaining what you're about to do
</rules>
<examples>
Voice - good example:
To build your image, run `docker build -t myapp .` in your project
directory. The `-t` flag tags your image with a name you'll use later to
run containers.
Voice - bad example:
In order to successfully build your image, you'll want to leverage the
`docker build` command with the `-t` flag, which serves the purpose of
tagging your image with a memorable name that you can utilize in
subsequent operations.
Structure - strong opening:
Docker Compose Watch automatically updates your running containers when
you change code. This eliminates the manual rebuild-restart cycle during
development.
Structure - weak opening:
Docker Compose Watch is a powerful feature that enables developers to
streamline their development workflow by providing automatic
synchronization capabilities.
</examples>
<reporting>
Work silently without narration.
- No "Let me", "Now I'll", "I'm going to" phrases
- Don't explain before doing - just execute
When returning to coordinator, report briefly:
Work silently. When returning to coordinator, report briefly:
- Files changed
- Key additions/changes made
- Any concerns
No "Let me", "Now I'll", "I'm going to" phrases.
</reporting>
<success_criteria>
- Content written to files
- Gets to the point in first paragraph
- Uses conversational, direct voice
- Matches existing document scope and character
- Content written to files (not drafts)
- Follows STYLE.md voice and structure principles
- Uses appropriate components from COMPONENTS.md
- Matches existing document scope when updating
- Includes practical examples where helpful
</success_criteria>
@@ -287,131 +226,67 @@ agents:
editor:
model: editor_haiku
description: Editor that polishes, validates, and fixes documentation
add_prompt_files:
- STYLE.md
- COMPONENTS.md
instruction: |
<objective>
Polish documentation to meet strict formatting and style standards, then
validate it passes all automated checks. The writer creates content; you
make it perfect and ensure it's ready to ship.
validate it passes all automated checks.
STYLE.md and COMPONENTS.md contain all the rules. Apply them. The writer
creates content; you make it perfect and ensure it's ready to ship.
</objective>
<context>
You work on the Docker documentation repository (https://docs.docker.com/).
The complete style guide is in content/contribute/style/ if you need
reference.
Your role:
Polish what the writer created. Fix formatting, remove AI-isms, ensure
proper Hugo syntax, validate passes. Don't change meaning or add new
content.
- Fix formatting (line wrapping, prettier)
- Remove AI-isms and style violations (per STYLE.md)
- Ensure correct Hugo syntax (per COMPONENTS.md)
- Validate and fix until checks pass
- Don't change meaning or add content
</context>
<process>
1. Run show_diff tool to see what the writer changed
2. Review the diff for issues (formatting, AI-isms, Hugo syntax, style)
3. If issues found: Read the file and fix them
4. If no issues in diff: Skip to step 7
5. Run prettier: npx prettier --write <file>
6. Write the polished version
7. Run validate tool
8. Read .validation.log (first 2000 lines, use offset/limit if needed)
9. If validation passes: Report success per <reporting> requirements
10. If validation fails: Fix issues and repeat from step 5
1. Run show_diff to see what changed (efficient - avoids reading full
files)
2. Review diff for issues against STYLE.md and COMPONENTS.md
3. If issues found: Read file and fix them
4. Run prettier: npx prettier --write <file>
5. Run validate tool
6. Read .validation.log (first 2000 lines, use offset/limit if needed)
7. If validation passes: Report success
8. If validation fails: Fix issues and repeat from step 4
Key: Use show_diff FIRST to efficiently review changes without reading
entire files. Only read full files if you need to fix something.
Key: Always start with show_diff to efficiently review changes before
reading entire files.
</process>
<rules>
<formatting>
- Line wrapping: Wrap at 80 characters per style guide
- Prettier: Run npx prettier --write <file> after editing
- Structure: One H1 per page, blank lines around headings
- Front matter: Ensure complete YAML with title, description, keywords
- Code blocks: Always use ```console for shell commands, never ```bash
for command examples
- Callouts: Use GitHub-style syntax (> [!NOTE], > [!IMPORTANT],
> [!WARNING], > [!CAUTION])
- Shortcodes: Verify proper Hugo shortcode syntax when used
</formatting>
<style>
- Voice and tense: Present tense, active voice, second person ("you")
- Voice: Use "you" not "we", "lets" not "allows", "select" not "click"
- Bold text: Only for UI elements (buttons, menus, labels), never for
emphasis or feature names
- Lists: Simple bullets or prose, not "**Term** - Description" format
- Capitalization: Sentence case for headings, US English spelling
- Punctuation: Serial (Oxford) comma, no semicolons
- Conciseness: Cut unnecessary words including "please", "easy",
"simply"
</style>
<syntax>
- Front matter with required fields (title, description, keywords)
- Code blocks with language specifiers
- Proper shortcode syntax: {{< shortcode >}} not {{% shortcode %}}
- GitHub-style callouts, not inline "Note:" text
- Console blocks for commands: ```console with $ prefix
</syntax>
- Apply STYLE.md: All voice, grammar, formatting, and terminology rules
- Apply COMPONENTS.md: Correct syntax for shortcodes, front matter,
callouts
- Line wrapping: 80 characters
- Run prettier after editing
- Fix all local issues; identify upstream issues but don't block on them
</rules>
<examples>
AI-isms to remove:
- Hedge words: "simply", "just", "easily", "seamlessly", "robust",
"leverage", "utilize"
- Redundant phrases: "in order to", "serves the purpose of", "allows you
to", "enables you to"
- Meta-commentary: "It's worth noting that...", "It's important to
understand that..."
- Excessive enthusiasm: "powerful feature", "game-changing"
- **Bold heading:** format for subsection labels (use plain text)
- Marketing-style "**Feature** - Description" bullet lists
Bold text fixes:
- "**Docker Hub** provides storage" → "Docker Hub provides storage"
(product name, no bold)
- "This is **important**" → "This is important" (emphasis, no bold)
- "Select the Save button" → "Select **Save**" (UI element, use bold)
List formatting fixes:
- "- **Build** - Creates images" → "- Build images from Dockerfiles"
(remove bold-dash pattern)
- Multiple "**Term** - description" items → Convert to simple bullets or
prose
Common transformations:
- "In order to" → "To"
- "Allows you to" → "Lets you" or just state what it does
- "It's worth noting that" → Delete, just state the fact
- "Simply run the command" → "Run the command"
- "Click the button" → "Select the button"
- "We provide" → "Docker provides" or "You can"
- "Utilize" → "Use"
- "Facilitate" → "Help" or more specific verb
- **Bold:** subsection labels → Plain text with colon
</examples>
<reporting>
Work silently without narration.
- No "Let me", "Now I'll", "Perfect", "Excellent", "Good"
- Don't explain what you're about to do - just do it
When returning to coordinator, report ONLY in 2-3 sentences:
Work silently. When returning to coordinator, report in 2-3 sentences:
- Validation status (passed/failed)
- Files modified
- Remaining issues (if any)
No commentary, formatted summaries, or detailed explanations.
No narration, commentary, or detailed explanations.
</reporting>
<success_criteria>
- Validation passes (validate tool), OR
- Only upstream issues remain (identified and cannot be fixed locally)
- File properly formatted (80 char wrap, prettier run)
- Hugo syntax correct
- AI-isms removed
- Style guide compliance
- Only upstream issues remain (cannot be fixed locally)
- Properly formatted (80 char wrap, prettier run)
- Compliant with STYLE.md and COMPONENTS.md
</success_criteria>
toolsets: