Home • Explore • Blog • CI
☰



docker
4th chunk of `content/contribute/style/formatting.md`
f67b54d88a14e823781f3669e8b519f96b9977c9c1c31f950000000100000ccf
| 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 |
Title: Documentation Style Guide: Navigation, Optional Steps, Placeholders, Tables, File Types, and Units
Summary
This section outlines style guidelines for Docker documentation, covering navigation instructions (location then action, brevity, and reason-first steps), marking optional steps, using placeholders, best practices for tables (sentence case headings, avoid empty cells), correct ways to refer to file types (formal name instead of extension), and the proper formatting for units of measurement (abbreviated form in all caps with a space).