update-docs

Keep documentation in sync with code. Run this after code changes to find and fix stale, missing, or unclear documentation.

Scope

Documentation lives in two places:

1. Source-level: module docs, docstrings, inline comments, README files adjacent to the code.
2. Docs site: docs/src/ (Mintlify). Architecture pages, product pages, internal references.

Both layers must agree with each other and with the code.

Phase 1: Identify what changed

Run git diff (or git diff HEAD if staged) to see the code changes. For each changed file, note:

• new modules, functions, types, or public APIs
• renamed, moved, or deleted symbols
• changed behavior, contracts, or invariants
• new dependencies or integration points

Phase 2: Update source-level docs

Apply the /comment skill principles to every changed file.

Module docs must answer three questions

A reader opening the file cold must know within 30 seconds:

1. What does this module do?
2. Why does it exist? (What problem does it solve? Why is it separate from the neighboring module?)
3. Where does it fit? (Who calls it? What does it depend on?)

If the code change alters any of these answers, update the module doc.

Least experienced reader rule

• spell out every acronym on first use (TLV, VSOCK, PTY, CRD, NFS, etc.)
• include concrete examples for non-obvious formats, protocols, or transformations
• explain domain concepts inline, not by reference to external knowledge
• labeled diagrams for wire formats, byte layouts, state machines

What to check per changed file

• [ ] Module doc: still accurate? Answers what/why/where?
• [ ] Public function/type docs: still match behavior? Justify existence of non-obvious wrappers?
• [ ] Inline comments: pass the deletion test? (Would removing the comment lose information the code alone cannot convey?)
• [ ] Byte-layout maps: present for any binary packing code?
• [ ] Acronyms: expanded on first use in this file?
• [ ] Cross-references: intra-doc links ([crate::module], manpage citations) still point to correct targets?
• [ ] README in the module directory: still accurate?

What NOT to add

• comments that restate what the code says
• comments narrating control flow ("now we check if...")
• section headers that label the next function call
• doc comments on fields where the name + type are sufficient

Phase 3: Update docs site

Check whether the code change affects any page in docs/src/.

Decision tree

1. New subsystem or service: add a page under the appropriate group in docs/src/docs.json. Follow the structure of existing peers.
2. Changed architecture or contracts: update the relevant architecture page (e.g., dcs/architecture/runtime.mdx for runtime changes).
3. Changed public API surface: update the product page and any getting-started or pricing pages that reference the API.
4. Internal-only change (refactor, extract helper, rename private symbol): usually no docs-site change needed. Only update if the architecture page describes the internal structure at a level that would now be wrong.

Docs site principles

The docs site explains what the system does and why. Source comments explain how the code works. Do not put implementation details (wire formats, trait bounds, helper functions) on the docs site. Do not put architectural context (system diagrams, ownership tables, product contracts) only in source comments.

Least experienced reader applies here too. A new engineer reading the docs site should understand the system without opening the code. Spell out jargon. Define terms inline. Use diagrams when they clarify a mechanism.

Docs site checklist

• [ ] Nav config (docs/src/docs.json): new pages added? Deleted pages removed? Group structure still makes sense?
• [ ] Architecture pages: still accurate after the code change?
• [ ] Cross-references between pages: no broken links to deleted or renamed pages?
• [ ] Product pages: descriptions match current behavior?
• [ ] Diagrams: still reflect the actual data flow / component structure?

Phase 4: Verify consistency

Check that the three layers (code, source docs, site docs) agree:

• if the code says X, the module doc should say X
• if the module doc says X, the architecture page should not say Y
• if a page references a CRD, function, or file path, verify it exists

Common drift patterns

• architecture page describes a deleted component
• module doc references a renamed function or type
• getting-started page shows an API call with old parameter names
• README lists source paths that moved in a refactor
• diagram shows a component that was merged into another

What to skip

• generated code (OpenAPI specs, protobuf output): these have their own update pipelines
• test files: tests are self-documenting through assertion names
• changelog or release notes: separate process
• docs for unchanged code: do not speculatively improve docs outside the scope of the code change

Anti-patterns

• Docs-only PR with no code change. If the docs drifted, the code change that caused the drift should have updated the docs. Fix forward, but note the gap.
• Copying the full implementation into prose. The docs site is not a line-by-line translation of the code. It explains the system at the level a human needs to make decisions.
• Architecture diagrams in source comments. System-level diagrams belong on the docs site where they render. Source comments get file-local diagrams only (byte layouts, small state machines).
• Updating docs site but not source docs. Both layers must be updated. A new reader might enter through either path.