Glossary Style Guide

Validated on 10 Dec 2024 • Last edited on 18 Dec 2024

Glossary articles define DigitalOcean-specific terminology.

When to Add an Entry to the Glossary

Before you add an entry to the glossary, ask yourself the following questions:

  • Is this a DigitalOcean-specific term (including general computing terms that have a specific, different meaning on our platform)?

  • Does this term have a clear definition on our platform?

  • Is this term potentially confusing or unfamiliar to readers without more information?

If the answer to any of these questions is no, reconsider making a new glossary entry.

Concept DO-Specific? Clearly defined? Confusing or unfamiliar? Add to glossary?
SSH keys No. SSH keys are not specific to DO. Yes. Yes, SSH keys are a common stumbling block for new users. No.
App spec Yes. This is specific to App Platform. Yes. It has a consistent meaning on the platform. Yes. This is a unique concept for App Platform. Yes.
Function Yes, even though the term function has a lot of uses in computing. Yes, it refers to a specific DO product. No. In context of a serverless functions offering, this term is self-evident. No.
1-Click App Yes. This is specific to Marketplace. Yes, for both Droplets and DOKS. Yes. A user new to DO won’t know what this is without learning first. Yes.

How to Write a New Glossary Entry

The description front matter of a glossary entry is what the [glossary shortcode]/style/hugo/shortcodes/glossary/ hover text displays.

A glossary description must:

  • Give the most important, high-level definition of the term.
  • Be a sentence fragment.
  • Stay within 25 words.

A glossary description must not:

  • Go into excessive detail.
  • Include multiple sentences.
Prefer Avoid
Droplet IP addresses that reserved IPs bind to. Each newly created Droplet receives an anchor IP address, and when you assign a reserved IP to a Droplet, the reserved IP maps traffic to the anchor IP instead of the Droplet’s public IP.

The content of the remaining glossary entry provides additional information about the term for a reader to understand the general concept, if any.

The content should:

  • Be concise, direct, and factual.
  • Provide the necessary context for the product it relates to.
  • Stay within two paragraphs.
  • Align to standard product tones tone.
  • Link to more detailed product documentation where helpful.

The content should not:

  • Include technical instructions or how-to content
  • Include pricing information, limits, or other product reference information
  • Include marketing material, calls to action, or other advertising.
Prefer Avoid
In App Platform, a job is a resource that runs server-side code at a scheduled time. Like workers, jobs are not accessible from the internet. Learn more about the proramming languages supported for jobs in the App Platform documentation. A job is a type of resource that is running server-side code written in a supported programming language, such as Python, Ruby, Go, Node.js, or PHP, and is not internet-accessible. You can add a job to your app from the control panel.

Authorship Process

Use the glossary-terms archetype to create a glossary entry:

hugo new products/glossary-terms/<name-of-glossary-entry>

The filename is what the glossary shortcode uses to look up the term to display a tooltip.

If you’re adding a new top-level glossary term (i.e. a new product to tag glossary entries with), use the glossary archetype to set front matter for the new term:

hugo new products/glossary/<name-of-glossary-term>

Add <--more--> after the introductory definition to use it as the description for the page (and therefore omit description: from the page front matter).

Control Panel Blog Pricing Careers Terms Privacy Status API Docs Tutorials Support