Contribution Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• content/contribute/_index.md
• content/contribute/checklist.md
• content/contribute/file-conventions.md
• content/contribute/guides.md
• content/contribute/style/formatting.md
• content/contribute/style/grammar.md
• content/contribute/style/voice-tone.md
• content/contribute/ui.md
• content/contribute/components/call-outs.md
• content/contribute/style/recommended-words.md

This document outlines the process and standards for contributing to the Docker documentation. The guidelines are designed to make it as easy as possible for community members to contribute, ensuring that the documentation remains clear, consistent, and helpful for all users. The documentation is built using Hugo, with content primarily written in Markdown.

Contributions can range from reporting issues and suggesting improvements to editing content and writing new usage guides. All contributions are managed through the docker/docs GitHub repository and are highly valued by the Docker community.

Sources: CONTRIBUTING.md:3-9, content/contribute/_index.md:19-23

Getting Started

Before contributing code or content, you can participate by reporting issues or suggesting improvements.

Reporting Issues

If you find a problem with the documentation content or the site itself, you can submit an issue through the GitHub issue tracker. This is also the appropriate channel for requesting improvements or suggesting new content.

Sources: CONTRIBUTING.md:13-17

Local Development Setup

To edit content, you must set up a local development environment. This involves forking the repository, cloning it, and using Docker to build and serve the site. Docker Desktop version 4.24+ or Docker Engine with Compose v2.22+ is required.

The following diagram illustrates the local setup process.

The specific commands for this setup are:

1. Clone your fork:

   $ git clone https://github.com/%3Cyour-username%3E/docs
   $ cd docs
   

2. Configure upstream remote:

   $ git remote add upstream https://github.com/docker/docs.git
   $ git remote set-url --push upstream no_pushing
   

3. Create a branch:

   $ git checkout -b <branch>
   

4. Start the development server:

   $ docker compose watch
   

Sources: CONTRIBUTING.md:40-55

Before submitting a pull request, run local tests to check for broken links and formatting errors:

$ docker buildx bake validate

Sources: CONTRIBUTING.md:65-69

Contribution Workflow

The general workflow for contributing changes follows standard Git practices. It involves creating a pull request from your fork, which is then reviewed.

This sequence diagram shows the high-level contribution process.

General Guidelines

• Keep pull requests focused; avoid touching a large number of files in a single PR.
• Do not change whitespace or reformat parts of a file you are not editing.
• Check the preview deployment generated by GitHub Actions to verify your changes.

Sources: CONTRIBUTING.md:31-38

Content and File Conventions

All content is written in Markdown files located in the /content directory.

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-12

Front Matter

Each Markdown file must begin with a YAML front matter block. title, description, and keywords are required.

Key	Required	Description
title	Yes	The page title, rendered as an <h1> header.
description	Yes	A sentence describing the page content for HTML metadata.
keywords	Yes	A comma-separated list of keywords for HTML metadata.
aliases	No	A list of pages that should redirect to this page.
notoc	No	If true, no in-page Table of Contents is generated.
toc_min	No	The minimum heading level (e.g., 2 for <h2>) in the TOC. Defaults to 2.
toc_max	No	The maximum heading level (e.g., 3 for <h3>) in the TOC. Defaults to 3.
sitemap	No	If false, excludes the page from sitemap.xml and search engine indexing.

Sources: content/contribute/file-conventions.md:16-40

An example of front matter:

---
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/
toc_max: 4
---

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

Style and Voice

Consistency in style and voice is crucial for a cohesive documentation experience.

Voice and Tone

The voice should be knowledgeable, experienced, and respectful. The tone is generally informal but must always prioritize clarity.

• Correct, Concise, Complete, Clear: These are the four principles of writing.
• Honest: Provide all facts without misdirection.
• Concise: Be clear and to the point.
• Relaxed: The demeanor should be casual but not lazy.
• Inclusive: Welcome developers of all experience levels.
• Positive Language: Emphasize what users can do, not what they can't.

Sources: content/contribute/style/voice-tone.md:6-38

Grammar and Capitalization

• Use US English.
• Spell out acronyms on first use (e.g., "single sign-on (SSO)").
• Use sentence case for titles and headings.
• Capitalize product names like Docker Desktop and Docker Hub.
• Use the serial (Oxford) comma.
• Avoid semicolons; use two sentences instead.

Sources: content/contribute/style/grammar.md:6, 11-15, 30-32, 107-109

Recommended Word Choices

To maintain consistency, use the recommended terms.

Don't Use	Use Instead
click	select
e.g.	for example, such as
enable/disable	turn on/turn off (unless it's a technical term in the UI)
repo	repository
sign on, log in	sign in
register	sign up
we	Focus on the user's actions

Sources: content/contribute/style/recommended-words.md:6-90

Formatting and Components

Headings and Links

• Front-load headings with the most important words.
• Keep headings short (max 8 words).
• Page titles should be action-oriented (e.g., "Install Docker Desktop").
• Link text should be short and descriptive. Avoid "click here".

Sources: content/contribute/style/formatting.md:6-15, 41-47

Code Blocks

• Use single backticks for inline code: docker run.
• Prefix commands with $ for non-privileged shells and # for privileged shells.
• Place command output in a separate code block.
• Use ... to indicate omitted code.

Sources: content/contribute/style/formatting.md:53-83

Callouts

Use callouts to emphasize information. They are created using blockquote syntax.

Type	Use Case	Color
[!WARNING]	Signals actions that may cause damage or data loss.	Red
[!IMPORTANT]	Signals actions that may cause lower-magnitude issues.	Yellow
[!NOTE]	For information that is tangential or may not apply to all readers.	Blue
[!CAUTION]	For critical warnings.
[!TIP]	For helpful tips.

Sources: content/contribute/style/formatting.md:88-107, content/contribute/components/call-outs.md:28-56

Example of a NOTE callout:

> [!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.

Sources: content/contribute/components/call-outs.md:30-35

UI Elements

• Use bold for UI element names (e.g., "Select Save.").
• Follow capitalization as it appears in the UI.
• Use consistent terms for 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
toggle	A binary control (on/off)

Sources: content/contribute/ui.md:9-15, 44-58

Writing Usage Guides

Special guidelines apply when writing tutorial-style usage guides.

Guide Metadata

Guides require specific front matter to aid in discovery and filtering.

---
title: Deploy a machine learning model with Docker
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...
tags: [machine-learning, deployment]
languages: [python]
params:
  time: 30 minutes
---

Sources: content/contribute/guides.md:27-41

Guide Structure

• Single-page guides are created as a single markdown file in content/guides/.
• Multi-page guides are a directory with an _index.md for the introduction and separate files for each step.
• Guides should include an introduction, prerequisites, setup, implementation steps, and a conclusion.

Sources: content/contribute/guides.md:52-80

Submission Process for Guides

The process for submitting a new guide involves a proposal and review stage.

This diagram shows the guide submission workflow.

Contribution Checklist

Before submitting your contribution, review this checklist:

• Used active voice.
• Written clear, concise sentences.
• Used subheadings and lists to break up long text.
• Started page titles with a verb.
• Checked for broken links and images.
• Used bold for UI elements.
• Completed a final spelling, punctuation, and grammar check.

Sources: content/contribute/checklist.md:9-40

Content Not Edited Here

Some documentation content is maintained in upstream repositories and is only vendored into docker/docs. Changes to this content must be made in the source repository.

• CLI reference documentation: docker/cli, docker/buildx, docker/compose
• Dockerfile reference
• Docker Engine API reference
• Compose specification

If you find an issue in this content, you can still raise an issue in the docker/docs repository for tracking.

Sources: CONTRIBUTING.md:73-93