Article Structure

Clear, consistent article structure helps readers understand where they are, what to expect, and how to move through content efficiently. A predictable structure improves scanning, comprehension, and task completion across documentation types.

Use the guidance below to structure articles based on their purpose while maintaining a consistent hierarchy and flow.

Headings

Use headings to create a clear structure that reflects information hierarchy and helps readers scan and understand the article’s purpose.

Use a consistent heading hierarchy with no skipped levels. Do not go beyond Level 4 headings in any article.

Avoid overusing headings for short sections. Combine content when separation adds no clarity, and do not create empty or placeholder sections.

Front Matter Descriptions

Descriptions explain what an article covers and help readers decide whether to read it.

Descriptions should:

• Start directly with the subject or solution.
• State what the reader gets from the article.
• Use plain, direct language.
• Avoid narrative framing or promotional tone.

Do not begin descriptions with phrases such as:

• “Learn more about…”
• “This article explains…”
• “In this guide…”

Descriptions do not need to follow a rigid template, but they should consistently answer: What is this and why would I read it?

For example:

Use Agent Development Kit to create and manage agents on Gradient™ AI Platform.

A list of available agent evaluation metrics and their definitions.

Autogenerated Descriptions

Some descriptions are autogenerated, such as those used in Quickstarts and landing pages.

Keep autogenerated descriptions unless they are incorrect, misleading, or outdated. Avoid overriding them without a clear reason, as consistency across indexes is often more important than perfect phrasing.

Summaries

Summaries describe a concept or product as it exists, without promotional or marketing language. They typically appear at the top of articles or in index and overview pages.

Good summaries:

• Define the product or concept clearly.
• Provide essential context.
• Avoid hype or emotional language.
• Use precise, technical wording where appropriate.

For example:

DigitalOcean Gradient™ AI Bare Metal GPUs are dedicated, single-tenant servers with 8 GPUs of various models that can operate standalone or in multi-node clusters.

The DigitalOcean Container Registry (DOCR) is a private Docker image registry that lets you store and manage private container images. DOCR integrates natively with Docker environments and DigitalOcean Kubernetes clusters.

DigitalOcean Droplets are Linux-based virtual machines (VMs) that run on top of virtualized hardware. Each Droplet you create is a new server you can use, either standalone or as part of a larger, cloud-based infrastructure.

Procedural Article Structure

Procedural articles guide users through a sequence of actions to complete a task.

Use the following structure:

1. Title (level 1)
2. Introduction paragraphs, including prerequisites if needed

• Use level 2 headings only if the introduction requires structure.

3. Imperative verb step titles (level 2)

   Typical titles: Verb … Using Automation / Verb … Using the Control Panel – control panel first then automation second

4. Imperative verb sub-steps (level 3), if required

For the Using Automation Lvl 2: typically format Lvl 3 as Verb … via CLI / Verb … via API For using Control Panel: lvl 3: is typically sub-steps to complete the task in the control panel dictated by the Control Panel UI if that makes sense

5. Additional level 2 steps as needed
6. Conclusion or next steps (level 2), if necessary

For example:

# Create a Load Balancer

Introductory paragraphs

## Configure Networking

### Assign Subnets

## Attach Droplets

### Select Droplets

## Verify Configuration

## Next Steps

Critical Context and Self-Sufficiency

Each page must stand on its own. A reader (or an LLM) arriving at a page with no prior context should receive accurate, complete information without needing to read parent pages or related articles.

Apply this principle when writing or reviewing any page:

• State preview status, feature flag requirements, and significant platform constraints (such as regional availability or required plan tier) near the top of the page, not only in an overview or parent page.
• Use the shared public-preview-notice include (`

• Do not rely on callouts in a different section or article to cover a constraint. If the constraint affects what a user can do on this page, state it on this page.

For a structured review checklist, see Self-Sufficiency Review Checklist.

For guidance on writing content that is well-structured for both human readers and LLMs, see LLM-Friendly Content.

Errors and Blocking States

Present errors with verified causes and resolution steps. Place resolution steps immediately after the error description to maintain a clear path from problem to solution.

Verb Forms in Procedural Headings

Use the imperative mood for headings that introduce procedures to clearly state the required action.

Imperative headings make task-based documentation clearer, more consistent, and easier to scan.

Use the gerund or a noun phrase only when a section explains a concept or behavior and doesn’t include a procedure.

Small or Focused Articles

Some articles address a very small, specific task, concept, or solution and do not require full procedural structure.

These articles typically include:

1. Title (level 1)
2. Short introduction paragraph
3. Article body, using level 2 or level 3 headings
4. Conclusion paragraph, if necessary

Avoid adding structure that does not improve clarity.

Using Numbered Steps

Use numbered steps whenever a procedure requires actions to be performed in order, such as when the procedure:

• Clearly signals sequence (“do this, then this”).
• Benefits from being easy to scan and follow.
• Represents a standard procedural task.

Even in short or focused articles, use numbered steps if users must complete actions in a specific order to achieve the intended result.

Numbered steps are usually unnecessary when the procedure is extremely short and primarily consists of a single code example with minimal setup or decision-making. For example, scaling an app to a fixed size in App Platform does not require numbered steps because the action is effectively a single operation.

Support Article Structure

Support articles are user-focused resources that answer questions directly and help users diagnose or resolve issues efficiently. Support articles should prioritize resolution over narrative.

Use the following structure:

1. Title, phrased as the user’s question
2. Description, stating the solution or outcome
3. Introduction to the issue
4. Background or explanation, only if necessary
5. Steps or sections that resolve the issue
6. Conclusion or related actions, optional

Not every article needs every section, but each article should clearly guide the reader to the next step. For examples of effective support article structure, see the BIOS-level changes article and the database connection timeout article.

For detailed tone and troubleshooting guidance, see Support Articles.

Glossary Entry Structure

Glossary entries provide short, product-aware definitions that help readers understand DigitalOcean-specific terminology.

Glossary entries typically include:

1. Glossary term
2. Concise definition, written in the context of one or more DigitalOcean products
3. Short body, explaining how the term relates to DigitalOcean systems or features
4. Additional clarification, if necessary
5. Links or link cards to deeper product documentation

Each glossary entry serves as a single canonical definition. Avoid duplicating or fragmenting definitions across entries.

For complete rules, see the Glossary Style Guide.

Heading Workflow Visualization

The following diagram shows a typical heading workflow for complex procedural articles that include multiple sub-tasks or phases.

This structure works best when a task involves distinct steps that build on each other, such as configuration, validation, and follow-up actions. For example, this pattern fits articles like Deploy an RSS Reader on App Platform.

Not all procedural articles need this level of structure. Use this workflow only when it improves clarity. Simpler tasks should follow the guidance in Procedural Article Structure and use fewer headings. Choose the smallest structure that clearly communicates sequence and progress.

  flowchart TD
    H1["Title (level 1)"]
    I["Introduction and prerequisites"]
    S1["Step 1 (level 2)"]
    S1a["Sub-step (level 3)"]
    S2["Step 2 (level 2)"]
    S3["Step 3 (level 2)"]
    C["Conclusion or next steps"]

    H1 --> I
    I --> S1
    S1 --> S1a
    S1a --> S2
    S2 --> S3
    S3 --> C

    classDef boxStyle fill:transparent,stroke:#cfd6e4,stroke-width:1.5px,color:#cfd6e4,rx:10,ry:10;
    class H1,I,S1,S1a,S2,S3,C boxStyle;