Product Documentation Style Guide

The DigitalOcean Product Documentation Style Guide outlines the voice and tone we use in our docs, as well as our conscious decisions on grammar, punctuation, capitalization, and other elements of style.

Above all, we make choices to provide clarity to our readers. We also make decisions about the small details to keep our docs consistent and to prevent us and other contributors from repeatedly making the same calls.

Our style and our documentation are constantly evolving. Because we don’t always update all of our existing docs when we update our style guide, you may see older content that isn’t consistent. Always err on the side of following this guide.

Product Docs Grammar and Language

We follow the broader DigitalOcean style guide, with a few augmentations and small modifications.

DigitalOcean Style Guide

Guidelines for writing about DigitalOcean.

• Use use_your_<variable> for placeholders, like use_your_droplet_ip.

• Format dates in date/month/year order, as in 1 January 1970.

• Use first-person plural (we) when speaking as the author or as the voice of DigitalOcean. Use second-person singular (you) when addressing the user.

• In titles for pages in our product IA, use the singular of product names (e.g. Droplet Overview instead of Droplets Overview), except for Spaces.

• When adding external links, make sure the external content is maintained. Only link to unmaintained, time-bound content (like the DigitalOcean blog) from similarly unmaintained, time-bound content (like release notes).

• Avoid Latin, like “e.g.” or “i.e.”, and instead use “for example” or “that is”.

• Use the active voice, not the passive voice.

Detailed Reference

Product Docs Voice and Tone

DigitalOcean Product Docs use a calm, neutral, task-focused voice and tone that prioritizes clarity, precision, and task completion.

Documentation Types

How documentation structure and purpose vary by type while maintaining a consistent product documentation tone.

Screenshots

When and how to use screenshots in product documentation.

Glossary Style Guide

How to write and structure product docs glossary articles.

Documenting Code

How to document and format code examples clearly and consistently in Product Docs.

Formatting

Use consistent formatting to improve clarity, scannability, and accessibility across all documentation.

Apply the following rules consistently across all documentation:

• Use bold for GUI text.
• Use inline code for IP addresses, domains, commands, package names, filenames, paths, options, and flags.
• Use relrefs for internal links.
• Use notices sparingly, and only to call out important notes, warnings, or constraints.
• Use includes to reuse shared or repeated content.

Italics

Use italics sparingly to add clarity, not emphasis. Italics should help readers distinguish concepts, terms, or references without introducing unnecessary styling.