Documentation Skill

Universal guide for creating and maintaining project documentation. Works with any project type, docs tooling, and team structure.

Reference Files

Read these as needed — don't load everything upfront:

Documentation Philosophy

Follow these principles when writing or updating documentation:

1. Document what isn't obvious from reading code — business rules, decisions, trade-offs, and operational procedures. Don't document what the code already says clearly.
2. Document decisions and rationale — "why" matters more than "what". Use ADRs for architecture decisions.
3. One source of truth per topic — prefer updating an existing doc over creating a new one. Never have two active docs describing the same current behavior.
4. Docs are part of "done" — every behavior-changing PR (feature, fix, refactor, integration, infra change) should update relevant docs in the same change.
5. Short, linked docs > long monolithic docs — five clear 1-page docs beat one 30-page document. Link between related docs.
6. Metadata on every doc — status, owner, and last-reviewed date make docs maintainable. Stale docs are worse than no docs.

Mandatory Workflow

Follow these steps in order for every documentation change.

Step 1: Check what already exists

Before creating anything new, search the docs/ directory (and the registry/index if the project has one). Check if a doc already covers the topic. Prefer updating existing docs over creating new ones.

Step 2: Determine where the doc goes

Use the decision guide (references/decision-guide.md) to find the right section. The two-step filter:

1. Is this about a single module? → modules/<module>/ subtree
2. Otherwise, match by purpose → see the table below

For the full flowchart with boundary cases, read references/decision-guide.md.

Step 3: Write or update the document

Every doc file must include this frontmatter:

---
title: '<doc title>'
summary: '<one-line purpose>'
status: active
owner: '<team-or-role>'
last_reviewed: YYYY-MM-DD
source_paths:
  - '<repo/path/used/as/source>'
replaces: '<old doc path, if replacing>'
replaced_by: '<new doc path, if being replaced>'
---

• status: draft | active | superseded | archived
• last_reviewed: always set to today's date
• replaces / replaced_by: only when superseding another doc

For the document body, read references/templates.md to get the right template for your doc type.

Step 4: Update the index

If the project uses a registry file or docs index (registry.md, docs/README.md):

1. New docs: Add an entry with path, type, status, and owner
2. Updated docs: Update last_reviewed date
3. Superseded docs: Change status, add note linking to replacement

Step 5: Update docs site (if applicable)

If the project uses a docs site tool (VitePress, Docusaurus, etc.), new pages must be added to the site configuration. Read the matching adapter in references/tooling/ for details.

Step 6: Handle superseded docs (only when replacing)

1. Move old doc to legacy/superseded/ (or archive/delete if no historical value)
2. Set status: superseded and add replaced_by in old doc's frontmatter
3. Add replaces in new doc's frontmatter
4. Update both entries in the index/registry

Project Type Adaptation

The standard folder structure works for any project, but different project types emphasize different sections. Read the matching reference file for specific guidance:

When to Document

Not everything needs a doc. Document when:

• Something costs time to understand from the code alone
• A decision has trade-offs worth recording
• A feature has business rules or edge cases
• An operational process would be hard to reproduce without a guide
• Someone new would have to ask the same question more than once

These are the signals that a topic deserves documentation.

Quick Checklist

Before submitting any documentation change:

• Searched for existing docs on this topic first
• Frontmatter is complete with today's date in last_reviewed
• Doc is in the correct section per the decision guide
• Index/registry updated (if project uses one)
• Docs site config updated (if project uses one, new pages only)
• Superseded docs handled properly (if replacing)
• Links between related docs are added