Documentation style guide

Cove documentation is organized first around the reader’s role and journey. Within those sections, the Diátaxis framework keeps different kinds of writing focused.

Place the page in the documentation structure

The primary navigation follows four reader destinations:

Section	Reader intent	Content
Get Started	Install Cove and complete a first useful experience	Installation how-to guides and introductory tutorials
User Guide	Use and administer a running Cove library	User-facing how-to guides and explanations
Developer	Work on Cove or build extensions	Developer tutorials, how-to guides, explanations, and API guidance
Reference	Look up exact behavior	Reference pages and terminology

Choose the reader section before the page type. A tutorial for a new Cove user belongs in Get Started, while an extension tutorial belongs in Developer. Shared contracts and durable product concepts belong in Reference. Existing page URLs do not need to mirror the navigation hierarchy.

Reserve Ecosystem for a future collection of integrations, extensions, and community resources. Do not add an empty section or use it as a substitute for extension guides and reference contracts.

Choose the page type within the section

Every documentation page should have one primary purpose.

Type	Reader need	The page should
Tutorial	Learn through a guided experience	Lead a new reader through a complete, reliable learning path.
How-to guide	Accomplish a specific goal	Give an experienced-enough reader a direct sequence of actions.
Explanation	Understand a concept or design	Build a mental model, connect ideas, and discuss reasons or tradeoffs.
Reference	Look up precise information	Describe facts, contracts, options, or terminology consistently and completely.

Do not make one page serve all four needs. Link between page types when a reader needs background, instructions, or exact details that would distract from the page’s main purpose.

Page type controls how the page is written; it is not a primary navigation label. Concepts shared across Cove should not be hidden in a developer-only hierarchy merely because developers also need them.

Structure each page for its purpose

Tutorials

• State what the reader will build or experience.
• List only prerequisites that must be satisfied before starting.
• Use a tested sequence with meaningful intermediate results.
• Explain enough for learning without branching into optional variations.
• End with a visible result and a small set of next steps.

How-to guides

• Name a concrete goal in the title.
• State the starting conditions before the procedure.
• Put required actions in order and keep alternatives clearly separated.
• Include commands, locations, and expected results where they remove ambiguity.
• End with a verification step and relevant troubleshooting links.

Explanations

• Open with the idea the page helps the reader understand.
• Define important terms or link to the terminology reference.
• Show relationships, lifecycle, boundaries, and tradeoffs rather than listing features.
• Use examples to clarify the model without turning the page into a procedure.
• Link to tutorials, how-to guides, and reference material for application details.

Reference pages

• State the scope and compatibility boundary.
• Organize information for scanning and lookup rather than narrative reading.
• Use consistent tables, names, units, defaults, and value formats.
• Separate supported behavior from reserved, deprecated, or unsupported behavior.
• Link to the source contract or relevant how-to guide when useful.

Related entity references should use a shared typed structure when readers benefit from comparing them. Media references define fields, relationships, file values, capabilities, availability, and lifecycle in src/data/reference/media.ts; its MEDIA_REFERENCE_SECTIONS constant owns their order, headings, and column names, while MediaReferenceTable.astro renders the rows consistently. Keep those headings as literal Markdown in the declared order so Starlight can add them to the table of contents, and put type-specific sections after the shared core. TypeScript validates the data shape and comparison vocabulary; review the MDX heading and component order as page structure rather than adding prose-specific tests.

Write with enough depth

A heading followed only by a list is usually an outline, not finished documentation. Add the context a reader needs to understand why the section matters, how its parts relate, and what changes when they make a choice.

Prefer a concrete example when a definition alone would leave the reader guessing. Prefer a table when several entries share the same attributes. Prefer prose when order, causality, or tradeoffs matter.

Do not repeat the page title as a Markdown level-one heading. Starlight renders the frontmatter title as the page’s single level-one heading, so body sections begin at level two.

Use Cove terminology consistently

The Terminology reference is the canonical short definition of Cove-specific concepts. Each term links to a canonical concept-reference page for its durable model, relationships, lifecycle, and boundaries.

Each terminology entry must:

• describe exactly one concept in exactly one sentence
• use the term as Cove uses it, not a broader industry definition
• distinguish the concept from a commonly confused term when necessary
• link its first useful mention to deeper documentation instead of expanding into a second sentence

When a concept needs more than one sentence, put lookup facts on its reference page. Create an explanation page only when readers also need a mental model, decisions, or tradeoffs, and link back instead of repeating the reference inventory.

Style and voice

• Address the reader as “you” when describing an action.
• Use direct, active language and present tense.
• Prefer Cove’s visible UI labels and public contract names over internal implementation names.
• Introduce abbreviations and specialized terms before relying on them.
• Keep warnings proportional and explain the consequence, not merely that something is dangerous.
• Avoid promotional language, filler introductions, and claims such as “easy” or “simple.”

Use sentence case for page titles and headings. Use backticks for commands, file names, configuration keys, code identifiers, and literal values; use bold text for visible UI labels.

Links and examples

Use descriptive link text that makes sense without its surrounding sentence. Prefer links to the most specific relevant page rather than a section landing page.

Examples must be generic, reproducible, and free of private environment domains, credentials, explicit entity identifiers, or names from a real media library. Commands should use readable long-form arguments when the utility provides them.

Page review checklist

Before publishing a page, confirm that:

• its primary Diátaxis type and reader need are clear
• its title and description accurately describe its scope
• it uses Cove terminology consistently
• it provides enough context to stand on its own
• instructions state prerequisites, expected results, and verification
• reference material distinguishes current support from limitations
• headings describe meaningful sections rather than divide short bullet lists
• links are specific and all examples are safe to publish
• the production documentation build passes

Repository structure and checks

• Marketing pages live in docs-site/src/pages/.
• Shared marketing styles live in docs-site/src/styles/global.css.
• Documentation lives under docs-site/src/content/docs/docs/.
• Existing URLs should remain stable during information-architecture changes unless redirects are provided.

Run the production build before publishing changes:

npm --prefix docs-site run build

GitHub Pages publishes the built site from the deployment workflow.