LLM-Friendly Content

LLMs retrieve, summarize, and cite documentation when answering user questions. Documentation that is well-structured for human readers is also well-structured for LLMs, but a few specific practices make the difference between content an LLM can use accurately and content it is likely to misquote or skip.

These guidelines complement the rest of the PDocs style guide. They do not replace any existing rules; they highlight the practices that most directly affect discoverability and accurate retrieval.

Front Matter Descriptions

A strong description field is the most important metadata signal for LLM summarization and search ranking. LLMs frequently use the description as a summary when citing a page.

Write descriptions that:

• Start directly with the subject or solution.
• State the page’s primary purpose in plain, direct language.
• Avoid narrative openers such as “Learn more about…”, “This article explains…”, or “In this guide…”.
• Avoid promotional or aspirational language.

Every page under content/products/, content/platform/, content/reference/, and content/support-articles/ must include a non-empty description field in its front matter. Do not leave descriptions empty or set to placeholder text.

For guidance on what makes a strong description, see Article Structure.

Headings as a Semantic Outline

LLMs parse headings as a document outline and use them to route queries to the right section of a page. Headings that are vague or inconsistent reduce retrieval accuracy.

When writing headings:

• Use a consistent hierarchy with no skipped levels (for example, do not jump from H2 to H4).
• Keep headings descriptive and specific. “Configure Networking” is more useful than “Step 2” or “Networking”.
• Do not go beyond Level 4 headings in any article.
• Use the imperative mood for procedural headings: “Create a Load Balancer”, not “Creating a Load Balancer” or “Load Balancer Creation”.
• Avoid headings that only make sense in context. Each heading should be interpretable on its own because LLMs may surface individual sections without surrounding context.

For full heading guidance, see Article Structure.

First Paragraph Clarity

The first paragraph is the most likely part of a page to be quoted or summarized by an LLM.

Make the first paragraph self-contained:

• Do not assume the reader has read a parent page or a previous article.
• Identify the product or feature by its full name.
• State what the product or feature does, or what the reader can accomplish with it, not what the page covers.

• Avoid self-referential phrasing in body prose. Phrases like “The examples in this guide show…” or “As covered in this article…” make the content harder to use out of context because they reference the document itself rather than the information. Replace them with direct statements: “The following examples show…” or “The steps above configure…”

For example, instead of “In this guide, we’ll walk you through creating a Droplet,” write:

Create a Droplet to provision a Linux-based virtual machine on DigitalOcean. You can configure its size, region, and OS during setup, and access it immediately after creation.

Code Examples and Explanations

LLMs summarize and quote code documentation. Code blocks without surrounding explanation are difficult to contextualize accurately.

Follow these practices:

• Introduce every code block with a sentence explaining what the code does, where to run it, and what to expect.
• Do not place a code block immediately after a heading with no intervening text.
• Follow significant code blocks with a sentence explaining key details, expected output, or constraints.
• Use output blocks to show expected results when they help confirm success or validate behavior.

For complete code documentation rules, see Documenting Code.

Consistent Terminology

LLMs match queries to content using term frequency and consistent naming. Inconsistent product and feature names reduce the chance that a page is retrieved for relevant queries.

• Use the exact product name as it appears in the DigitalOcean Control Panel and style guide.
• Introduce acronyms and abbreviations the first time they appear.
• Do not alternate between synonyms for the same feature (for example, avoid switching between “knowledge base” and “knowledge base store” for the same concept).

For spelling and terminology conventions, see the Vale vocabularies in the vale-package and the broader DigitalOcean style guide.

Critical Context on Every Page

LLMs often surface individual pages without surrounding context. Pages about preview features, features behind a flag, or features with platform constraints must state that context directly, on that page, without relying on readers to have seen another page first.

• If a feature is in public preview, state it prominently near the top of the page using the shared preview notice include (`

• If a feature requires opting in or enabling a flag, state the requirement near the top and link to where the user can complete the opt-in.
• If a feature has platform constraints (for example, it is not available in all regions or requires a specific plan), state those constraints on the page.

Do not link to another page as the sole source of a constraint. State the constraint on the page where the feature is documented.

For guidance on how to apply this during review, see the Self-Sufficiency Review Checklist.

Keyword Placement

Place important terms early in headings and descriptions, where they are most heavily weighted by search and LLM retrieval.

• Name the primary subject in the title and first heading.
• Use the primary term in the description and first paragraph.
• Avoid burying the key term in a long sentence or at the end of a paragraph.

This is not a call to keyword-stuff. The goal is clear, direct writing with the most important concept stated upfront, which benefits both human readers and LLM retrieval.