Language and Grammar

Acronyms

• On first use in a document:

  • For well-known acronyms, use the acronym first. Favor putting the full word or phrase in parentheses after.

  • For acronyms that are not well-known, put the full word or phrase first and the acronym in parentheses after.

• On subsequent uses in a document, favor the most commonly-used form and use discretion to favor readability. For example, “HTTP” is much more common than “Hypertext Transfer Protocol” (18 billion Google search results vs. 7 million, respectively).

Capitalization

• Use title case for headers, titles, and link titles.

• Use sentence case for items in bulleted and numbered lists.

• Capitalize the following terms:

  • Droplet
  • Spaces
  • 1-Click Application
  • Anything preceeded by “DigitalOcean”, like DigitalOcean Control Panel, DigitalOcean Load Balancer, and DigitalOcean Droplet Console.

• Lower case regular nouns, like load balancer, volumes, projects, reserved IP, and control panel.

• For companies, organizations, software, and similar things, use the capitalization of the project. UNIX was first developed in the 1970s. systemd runs as PID 1.

• Match the captalization of commands, even at the beginning of sentences and when otherwise using title case. How to Check File System Consistency with fsck

Formatting

Bold

• Use bold for GUI text.

In-Line Code

• Use in-line code for IP addresses, domains, commands, and package names.

• Do not use in-line code formatting in headers.

Grammatical Person

• 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.

Headers

• Use title case for headers, titles, and link titles.

• Use the singular of product names (e.g. Droplet Overview instead of Droplets Overview), except for Spaces.

Links

• 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).

Punctuation

Commas

• Use serial commas. Our products include object storage, block storage, and load balancers.

Exclamation Marks

• Use exclamation marks very sparingly.

Hyphens

• Use hyphenated compound modifiers. The file has DigitalOcean-specific syntax.

• Use suspended hyphens. Expect low performance from two- or three-node clusters.

• Use hyphens for ranges. Third-party tools support uploading 2-10 files at once.

Periods

• Use periods at the end of items in bulleted and numbered lists.

Spacing

• Use a single space to separate sentences.

• Use a space to separate numbers and units. The file size limit is 500 MB.

Word Conventions

• Use “log in to” rather than “log into”.

DigitalOcean Terminology

Use “control panel” or “DigitalOcean Control Panel” to refer to cloud.digitalocean.com.

IP Ranges

Use an address in the blocks reserved for documentation as per RFC-5737 for IPv4 and RFC-3849 for IPv6. Specifically, we use:

• 203.0.113.0/24 for example public IPv4 addresses
• 198.51.100.0/24 for example private IPv4 addresses
• 2001:DB8::/32 for example IPv6 addresses

Domains

Use example.com, example.net, example.org, or example.edu for documentation as per RFC-2606

Stand-In Variables

Use use_your_<variable> with in-line code formatting when indicating when the user should substitute their own value in a command. For example, use_your_droplet_ip or use_your_domain.

Technologies

• Use “macOS”, not “Mac”, “OS X”, or other variants.