Alyson Docs

Documenting Features

The standard workflow for adding or updating documentation.

Owner: @adminStatus: stableLast verified: 5/18/2026

This SOP applies whenever you add a new feature, service, runbook, or ADR — or substantially change an existing one.

TL;DR

  1. Pick a template from /templates.
  2. Copy it to the right folder.
  3. Fill it in (intake → draft → polish; see below).
  4. Update the last_verified field.
  5. Open a lightweight PR.

Where things go

What you're documentingFolderTemplate
Product feature / conceptdocs/10-product/<area>/feature.md
Service-level technical docdocs/20-services/<service>/service.md
APIdocs/20-services/<service>/api/api.md
Data table / schemadocs/30-data/service.md (adapt)
Runbookdocs/40-operations/runbooks/runbook.md
Architectural decisiondocs/50-adrs/adr.md
Working notes / scratchpadworking/(any)

The workflow

The hardest part of documentation is that the code alone doesn't tell the whole story — requirements, intent, edge-case rationale, and history live in your head. The workflow below extracts that.

1. Intake

Before drafting anything, write a rough brain-dump in working/<thing>-intake.md. It can be 10 lines or 200. Bullet points are fine. Include:

  • What it is, in your own words
  • Why it exists (what problem)
  • Anything non-obvious about it
  • Files / repos / endpoints involved
  • Open questions you have

This is the source of context the AI can't get from code.

2. Draft with AI

Open Claude Code (or Cursor / Codex) in the docs repo with the relevant code repo as a sibling. Use the /document-service or /document-feature slash command (see Using AI for Docs).

The agent should:

  • Read the intake file
  • Read the relevant code paths
  • Use the appropriate template
  • Ask you clarifying questions in the scratchpad
  • Produce a first draft

Iterate with the agent. The scratchpad in working/ is where it tracks progress so you can resume across sessions.

3. Polish

When the draft is good:

  • Move it from working/ to the right docs/ location
  • Set last_verified to today
  • Ensure all cross-links use /docs/... paths (not relative)
  • Delete the intake file or archive it
  • Run npm run check:links locally if your change adds many links

4. PR

Open a PR with a short description. Lightweight review — one reviewer, focused on accuracy and clarity. No nitpicking on prose.

Frontmatter discipline

Every doc must have:

---
title: <Title>
description: <One line>
owner: '@your-handle'
source_repos:
  - alyson-<repo>
source_paths:
  - 'alyson-<repo>/src/...'
last_verified: YYYY-MM-DD
status: stable | wip | deprecated
---
  • source_repos and source_paths drive the staleness checker. If any commit lands in those repos/paths after last_verified, the doc is flagged.
  • last_verified is updated by the doc author (or by the PR-bumper action if introduced later).
  • owner is the GitHub handle of the person responsible for keeping this doc current. Single owner — not a team.

When a doc goes stale

The staleness checker emails the Google Group and updates the dashboard. The doc's owner is on the hook to either:

  • Update the doc and bump last_verified, or
  • If nothing materially changed, just bump last_verified with a one-line PR.

Don't ignore stale flags. If a doc is genuinely irrelevant, mark status: deprecated (or delete it) instead of letting it rot.

What not to document

  • Code that's self-explanatory
  • Implementation details that will change every sprint (link to the code instead)
  • One-off scripts (unless they become runbooks)
  • Secrets, credentials, customer PII