Skip to main content

Write documentation

Use this workflow to add or update documentation in this repository. Every documentation change must use the Technical Documentation Architect agent with the $structure-technical-docs skill before it is submitted for review.

Required agent step

Using $structure-technical-docs is mandatory. Use it to draft the change or to review and revise a draft you wrote. A documentation change is not ready for review until this step is complete.

The agent helps structure the document for its readers. The contributor remains responsible for factual accuracy, source validation, security, and final judgment.

1. Find the right location​

Place the page under the section for its intended reader and task. Before creating a page:

  • search for an existing page that should be updated instead;
  • identify the source of truth for facts that may change; and
  • link to canonical information instead of duplicating it.

Keep one primary reader goal per page. Split substantially different goals into linked pages.

2. Ask the documentation agent​

Start a Codex task in this repository and explicitly invoke the skill. Give the agent the reader, desired outcome, facts or sources, and target path.

For a new page:

$structure-technical-docs

Create [target path]. The reader is [reader]. After reading it, they should be
able to [outcome]. Use [facts and source links]. Do not invent missing facts.

For an existing draft:

$structure-technical-docs

Review and revise [target path]. Preserve the facts and house style. Check the
reader goal, prerequisites, sequence, expected results, links, and recovery
guidance. Mark anything that requires validation.

The agent should inspect nearby documentation before editing so the change fits the existing structure and does not create a second source of truth.

3. Write for the reader's task​

Lead with what the reader will accomplish or understand. Use the lightest form that fits the goal:

  • Tutorial: help a novice learn through a controlled first success.
  • How-to: give steps for completing a real task.
  • Reference: make interfaces and behavior easy to look up.
  • Explanation: clarify a concept, boundary, or tradeoff.
  • Troubleshooting: help the reader diagnose and recover from a problem.
  • Decision: use an RFC for a proposal or an ADR for a settled decision.

State prerequisites, constraints, side effects, and expected results where they matter. Include recovery guidance for likely failures. Prefer short, verified examples over broad hypothetical ones.

4. Add page metadata​

Every documentation page begins with Docusaurus front matter:

---
title: Descriptive page title
sidebar_position: 1
description: State what the reader can accomplish or understand.
---

Use sentence case for titles unless a proper name requires otherwise. Choose a sidebar_position that places the page in the reader's expected sequence.

Use relative links for repository documentation:

[Definition of Ready](../employee-manual/planning-and-delivery/quality-standards.md#definition-of-ready)

Use Mermaid when a process, dependency, or relationship is materially easier to understand as a diagram than as prose.

5. Review the rendered result​

Run the local site while writing:

npm run start

Check the rendered page for:

  • correct sidebar placement and navigation;
  • readable headings, tables, code blocks, and diagrams;
  • links that lead to the intended source;
  • instructions that can be followed in order; and
  • no invented, duplicated, or stale facts.

If you wrote the first draft without the agent, run the mandatory agent review now and incorporate its corrections before continuing.

6. Build before review​

Run the production build:

npm run build

The change is ready for human review when the documentation agent has been used, the rendered page has been inspected, and the production build succeeds. If the build reports a broken link or invalid page, correct the source and run it again.

Review checklist​

  • $structure-technical-docs was used to draft or review the change.
  • The page has one clear reader and outcome.
  • Facts were checked against their sources of truth.
  • Commands, examples, links, and diagrams were verified where applicable.
  • The rendered page was inspected.
  • npm run build succeeds.