Edit

Documentation Conventions

Purpose: For contributors, defines how to add or update a page under docs/ so it stays consistent with the project’s documentation rules.

The documentation follows the Diátaxis framework for genre and a lifecycle-based directory layout for navigation. Every page must declare its genre in frontmatter and live in the lifecycle directory that matches what the reader is doing.

Directory layout

docs/
├── README.md                      # index page
├── getting-started/               # tutorials
├── operations/                    # how-to guides
├── reference/                     # reference
├── concepts/                      # explanations
└── contributing/                  # contributor-facing docs

Add new pages to the directory that matches the lifecycle category the reader is in. Do not create top-level tutorials/, how-to/, reference/, or explanation/ directories — the Diátaxis genre is in the frontmatter, not the path.

Required frontmatter

Every Markdown file under docs/ (except README.md) MUST start with this YAML frontmatter block:

---
id: kebab-case-slug
title: "Human-Readable Title"
sidebar_label: Short Label
description: One sentence summarizing what this page covers.
doc_type: tutorial | how-to | reference | explanation
audience: "platform engineers"
tags: [keyword1, keyword2]
---

Field rules:

  • id — lowercase kebab-case, unique across the docs set.

  • title — quoted, human-readable.

  • sidebar_label — 1–4 words for sidebar navigation.

  • description — one sentence; used for SEO and link previews.

  • doc_type — exactly one of tutorial, how-to, reference, explanation.

  • audience — comma-separated list of intended readers.

  • tags — at least one tag, lowercase, no spaces.

Required first paragraph

After the frontmatter, every page MUST start with a one-sentence purpose line in this shape:

Purpose: For <audience>, explains/shows <what>, covering <scope>.

Example:

Purpose: For platform engineers, lists every subcommand of opencenter-airgap, its flags, and behavior.

This makes the page’s scope obvious without scrolling.

One genre per page

Each page is exactly one Diátaxis genre. If a draft mixes a tutorial walkthrough, a step-by-step task, a schema, and a design rationale, split it into separate pages and cross-link them.

| Genre | Voice | Reader is | Lives under | |---|---|---|---| | Tutorial | Encouraging, walkthrough | Learning by doing | getting-started/ | | How-to | Direct, procedural | Completing a known task | operations/ | | Reference | Neutral, scan-friendly | Looking up exact facts | reference/ | | Explanation | Thoughtful, conceptual | Trying to understand "why" | concepts/ |

Style rules

These come straight from the project’s Documentation steering rule. Highlights:

  • Use plain sentences. Vary length naturally.

  • Make claims testable. Pin behavioral claims to a code path, a config file, or a command’s output.

  • Do not pad. Drop "It is important to note that," "In this section we will," "Furthermore," and similar throat-clearing.

  • Prefer measurable language over adjectives. "Builds in 20 minutes on 100 Mbps" beats "fast build."

  • One term per concept per page.

  • Keep paragraphs short. Use lists when the reader needs scan-ability; otherwise prose.

Linking to source

Reference docs should pin claims to source code. Use these formats:

  • src/opencenter_build/cli.py:build() — file plus function.

  • config/versions.env:KUBERNETES_VERSION — file plus variable.

  • zarf.yaml.template:components — file plus section.

Inline these into the prose, not as a footer block. They prove the claim and survive doc moves.

Self-contained pages

Every page must be useful on its own. State prerequisites on the page; do not require the reader to follow another link to know what they need. End with a short "Related" section linking to the next 2–4 pages a reader might want.

Local checks

Two scripts under hack/scripts/ enforce the structural rules:

hack/scripts/validate-doc-frontmatter.sh   # frontmatter completeness
hack/scripts/cli-help-dump.sh             # CLI surface vs reference

validate-doc-frontmatter.sh rejects the PR if any page under docs/ is missing required frontmatter or has a bad doc_type. cli-help-dump.sh produces the canonical CLI help output; diff it against docs/reference/cli-commands.md whenever you touch the CLI surface.

Updating the index

When you add a new page, add a row under the appropriate section of ../README.md[docs/README.md]. The index is the only place that lists every page; the directory structure does the rest.

Pull request checklist

Before opening a PR that adds or edits docs:

  • Frontmatter is complete and doc_type is correct.

  • First paragraph is a one-sentence purpose line.

  • Page does one genre.

  • Behavioral claims are pinned to code paths or commands.

  • hack/scripts/validate-doc-frontmatter.sh passes.

  • If the CLI changed, hack/scripts/cli-help-dump.sh matches the reference.

  • ../README.md[docs/README.md] was updated to link the new page.

  • ../../README.md[Project README].

  • ../README.md[docs/README.md] — index.

  • ../../CONTRIBUTING.md[Contributing Guide].