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 Tone

Empathize with the reader, be clear about who our audience is, and be clear about who we are.

Screenshots

When to include screenshots and what to include when you do.

Glossary Style Guide

How to write and structure glossary articles for the Product Docs glossary section of the website.

Documenting Code

How to document and format code in our docs.

Formatting

Use bold for GUI text. Use in-line code for IP addresses, domains, commands, package names. Use relrefs for internal links. Use notices very sparingly to call out important notes and warnings.