Content Style Guide

Relevant source files

The following files were used as context for generating this wiki page: - [content/contribute/style/voice-tone.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/style/voice-tone.md) - [content/contribute/style/grammar.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/style/grammar.md) - [content/contribute/style/formatting.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/style/formatting.md) - [content/contribute/style/recommended-words.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/style/recommended-words.md) - [content/contribute/file-conventions.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/file-conventions.md) - [content/contribute/checklist.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/checklist.md) - [content/contribute/ui.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/ui.md) - [content/contribute/guides.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/guides.md) - [CONTRIBUTING.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/CONTRIBUTING.md) - [content/contribute/components/call-outs.md](https://github.com/Alonso-pixel/docker-docs/blob/HEAD/content/contribute/components/call-outs.md)

The Docker Documentation Style Guide provides a set of standards for writing and formatting content. Its purpose is to ensure all documentation is correct, concise, complete, and clear, creating a consistent and helpful experience for all users. The guide covers voice and tone, grammar, formatting conventions, recommended terminology, and file structure.

Adherence to these guidelines is essential for all contributions. A Writing Checklist is available to help contributors verify their content before submission. The guide is a living document, evolving with the Docker platform and its community.
Sources: content/contribute/style/voice-tone.md:1-15, content/contribute/checklist.md:5-6, content/contribute/_index.md:21-23

Voice and Tone

Docker's documentation voice is knowledgeable, experienced, and empowering, but avoids arrogance. It is honest, concise, relaxed, and inclusive, aiming to inform and encourage developers of all experience levels. The tone is generally informal but prioritizes clarity over humor.
Sources: content/contribute/style/voice-tone.md:5-9, content/contribute/style/voice-tone.md:26-28

Core Principles (The 4Cs)

The foundation of Docker's writing style is built on four key principles: Correct, Concise, Complete, and Clear. These ensure that information is accurate, succinct, thorough, and easy to understand.
Sources: content/contribute/style/voice-tone.md:11-15

The following diagram illustrates the core writing principles.

Language and Phrasing

• Positive Language: Emphasize positive outcomes and capabilities rather than limitations. For example, describe what a subscription tier includes rather than what it lacks.
• Active Voice: Use active voice to make instructions clear and direct (e.g., "Increase productivity with Docker Desktop" instead of "Productivity can be increased...").
• Contractions: It is acceptable to use contractions like "you're" and "it's" to maintain a conversational tone, but they should not be overused. Negative contractions (can't, don't) should be avoided where possible.
• "We" vs. "You": The documentation should focus on the user. Avoid using "we" and instead frame sentences around how the user can accomplish a task.
  Sources: content/contribute/style/voice-tone.md:36-44, content/contribute/checklist.md:9-15, content/contribute/style/grammar.md:55-60, content/contribute/style/recommended-words.md:83-90

Grammar and Punctuation

All documentation must be written in US English.

Capitalization

The general rule is to use sentence case for almost everything, including page titles, headings, subheadings, and UI elements.
Sources: content/contribute/style/grammar.md:29-31

Element	Rule	Example
Headings & Titles	Sentence case	Install Docker Engine on Ubuntu
UI Elements	Match the UI exactly. If inconsistent, use sentence case.	Select the Save button.
Docker Solutions	Title case	Docker Extensions, Docker Hub
Job Titles	Capitalize only when preceding a name.	Chief Executive Officer Scott Johnston
Department Names	Capitalize the specific department name.	The Engineering department
Sources: content/contribute/style/grammar.md:33-53, content/contribute/ui.md:21-25

Numbers and Units

• Spell out numbers one through nine. Use numerals for 10 and above.
• Do not start a sentence with a number.
• For large numbers (five digits or more), use a space as a separator instead of a comma (e.g., 14 586).
• For units of measurement, use the abbreviated form in all caps with a space (e.g., 10 GB).
  Sources: content/contribute/style/grammar.md:92-109, content/contribute/style/formatting.md:170-176

Punctuation

• Serial (Oxford) Comma: Use the serial comma in lists of three or more items.
• Semicolons: Do not use semicolons. Rewrite as two separate sentences.
• Exclamation Marks: Avoid using exclamation marks.
• Parentheses: Avoid using parentheses in technical documentation to improve readability.
  Sources: content/contribute/style/grammar.md:115-136

Lists

• Use bulleted lists for short phrases and limit them to five items where possible.
• Ensure all list items are parallel in structure (e.g., all start with a verb).
• Start every list item with a capital letter unless it's a parameter or command.
• Do not use terminal punctuation on list items that are fragments.
  Sources: content/contribute/style/grammar.md:73-90, content/contribute/components/lists.md:9-11

Formatting and Components

Consistent formatting improves readability and helps users find information quickly.

Headings and Page Titles

• Headings should be short (max eight words), descriptive, and use plain, active language.
• Page titles should be action-oriented (e.g., "Install Docker Desktop").
• The page title and the Table of Contents (TOC) entry must match.
  Sources: content/contribute/style/formatting.md:8-19, content/contribute/checklist.md:26-27

Code and Commands

• Use single backticks (`) for inline code, such as filenames and commands.
• Use fenced code blocks for multi-line code samples.
• Prefix commands with $ for a non-privileged shell and # for a privileged shell.
• Place a single command per code block if it produces output. Command output should be in a separate block.
• Use ... to indicate omitted code.
  Sources: content/contribute/style/formatting.md:59-90

Callouts

Callouts emphasize important information. Use them sparingly to avoid clutter. GitHub-style blockquotes are used for alerts.

Callout Type	Markdown Syntax	Use Case
Note	> [!NOTE]	For information that is tangential or may not apply to all readers.
Important	> [!IMPORTANT]	To signal actions that may cause lower-magnitude issues.
Warning	> [!WARNING]	To signal actions that may cause data loss or software/hardware damage.
Caution	> [!CAUTION]	For critical warnings, stronger than WARNING.
Tip	> [!TIP]	To provide helpful advice or shortcuts.
Sources: content/contribute/style/formatting.md:92-118, content/contribute/components/call-outs.md:27-55

UI Elements

• Use bold formatting for the visible names of UI elements (buttons, tabs, dialogs, etc.).
• Write task-focused instructions (e.g., "Expand the Advanced options section" instead of "Select the zippy...").
• Use consistent terminology for UI components.
  Sources: content/contribute/ui.md:9-17, content/contribute/ui.md:27-31

The following table lists preferred terms for common UI elements.

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
tab	A selectable view within a window or page
dialog	A popup window for confirmations or options
toggle	A binary control (on/off)
Sources: content/contribute/ui.md:46-59

Recommended Word List

To ensure consistency, specific words and phrases are recommended or discouraged.

Use	Instead of	Rationale
select	click	select is more device-agnostic.
sign in	log in, logon	Standardized term for authentication.
repository	repo	Use the full term for clarity.
for example	e.g.	More readable and less jargony.
turn on / turn off	enable / disable	Avoids ableist language, though enable/disable is acceptable for technical features where it's part of the product's terminology.
username	account name	More standard and widely understood.
Sources: content/contribute/style/recommended-words.md:5-81

File and Content Structure

All documentation content resides in the /content directory and is written in Markdown with YAML front matter.

File Naming

• Keep file names short (1-2 words).
• Use a dash to separate words (e.g., add-seats.md).
  Sources: content/contribute/file-conventions.md:8-13

Front Matter

Every page requires a front matter block with title, description, and keywords. Other keys like aliases (for redirects) and toc_max are optional.

---
title: Install Docker Engine on Ubuntu
description: Instructions for installing Docker Engine on Ubuntu
keywords: requirements, apt, installation, ubuntu, install, uninstall, upgrade, update
aliases:
- /ee/docker-ee/ubuntu/
toc_max: 4
---

Sources: content/contribute/file-conventions.md:15-56

Guide Structure

Guides are a key content type and can be single or multi-page. Multi-page guides are structured as a directory with an _index.md for the introduction and separate markdown files for each step.

This diagram shows the file structure for a multi-page guide.

Contribution Checklist Summary

Before submitting a pull request, contributors should perform a final check to ensure their content aligns with the style guide. Key checks include:

• Using active voice.
• Writing clear, concise sentences.
• Breaking up long pages with subheadings and lists.
• Ensuring page titles are action-oriented and match the TOC.
• Verifying that all links and images work correctly.
• Bolding all UI elements.
• Performing a final spelling, punctuation, and grammar check.
  Sources: content/contribute/checklist.md:7-40

Conclusion

The Content Style Guide is a critical resource for maintaining the quality and consistency of Docker's documentation. By providing clear rules on voice, grammar, formatting, and structure, it empowers community members and internal writers to create content that is helpful, clear, and aligned with Docker's brand. Following these guidelines ensures that users have a seamless and positive experience when learning about and using Docker products.
Sources: content/contribute/_index.md:21-23, CONTRIBUTING.md:3-5