Docs Sync

Docs sync

Goal

Update documentation so it matches the current code and is easy for the target audience to follow.

Inputs to ask for (if missing)

• What changed (feature/bugfix/refactor) and who the docs are for.
• Which docs surfaces matter: README, /docs, wiki, runbooks, API spec, changelog, onboarding.
• Any required format/voice (company style guide, "keep it short", etc.).

Workflow (checklist)

1) Identify what changed

• Use the diff to locate impacted areas:
• git diff --name-only
• git diff

2) Inventory docs surfaces in the repo

• Common locations: README.md, docs/, CONTRIBUTING.md, CHANGELOG.md, openapi.*, schema.graphql, adr/, runbooks/.
• For Spring: check for generated OpenAPI/Swagger docs or endpoint annotations.
• For Next/TypeScript: check for docs pages, Storybook, or typed API clients.
• If your repo uses docs/ as the primary doc root, see references/docs-structure.md for a suggested layout.

3) Decide what needs updating

• Ensure docs cover:
• setup and local dev commands
• required env vars / config keys
• API contract changes (request/response examples)
• DB migrations and operational steps
• behavior changes visible to users
• If the change is an architectural/behavioral decision, add or update an ADR (use references/adr-template.md).

4) Apply edits with minimal churn

• Prefer small, targeted edits over rewrites.
• Add examples that are copy/paste runnable.
• Keep headings stable to avoid breaking deep links.
• Use templates in references/ when helpful.

5) Verify docs are consistent

• Run the repo's existing doc checks if present (md lint, docs build, site build).
• At minimum: ensure code fences match the actual commands and file paths, and env var names match the code.

Deliverable

Provide:

• The list of docs files updated and why.
• A short "How to verify" section (commands or manual checks).

ADR template

Use this as a starting point for docs/adr/NNNN-<short-title>.md.

# ADR NNNN: <Title>

- Status: Proposed | Accepted | Deprecated | Superseded
- Date: YYYY-MM-DD
- Owner: <team/person>

## Context
<What problem are we solving? What constraints exist? Link related docs/PRs.>

## Decision
<What are we doing and why?>

## Consequences
<What changes for users/developers/ops? What are the risks/tradeoffs?>

## Alternatives considered
- <Alternative> - <Why not?>

## References
- <Links to PRs, docs, tickets, other ADRs>

Reusable doc snippets

Environment variables section (template)

## Environment variables

| Name | Required | Default | Description |
|------|----------|---------|-------------|
| `EXAMPLE_VAR` | yes | - | What it controls |

Verification section (template)

````markdown

Verification

# unit tests
<command>

# build
<command>

````

Doc update checklist

• README: quickstart still works (install, dev, test, build).
• Setup: prerequisites and tool versions are current (Java/Node).
• Config: env vars + defaults documented; secrets clearly marked.
• API: endpoints or schema changes reflected (examples updated).
• DB: migrations/backfills documented; rollback notes included if needed.
• Ops: runbooks/alerts updated for behavior changes.
• Links: internal anchors and cross-links still valid.

Suggested docs/ structure (Spring + Next + Postgres)

Keep docs/README.md as the entrypoint with a short table of contents and links to each area.

docs/
  README.md

  adr/
    README.md
    0001-<short-title>.md

  backend/
    README.md
    local-dev.md
    configuration.md
    troubleshooting.md

    api/
      README.md
      openapi.md            (or link to `openapi.yaml` in repo root)

    database/
      README.md
      migrations.md         (Flyway/Liquibase conventions, how to run)
      schema.md             (high-level tables/relationships)

    operations/
      README.md
      deployment.md
      observability.md      (logs/metrics/tracing, dashboards, alerts)

  frontend/
    README.md
    local-dev.md
    configuration.md        (env vars, feature flags)
    troubleshooting.md
    architecture.md         (routing/data fetching patterns)

  runbooks/
    README.md
    incidents.md            (how to respond, where to look)
    common-issues.md

  reference/
    versions.md             (supported Java/Node/Postgres versions)
    environments.md         (dev/stage/prod differences)
    glossary.md

  templates/
    adr-template.md
    runbook-template.md

Notes

• Put "how to do X" docs near the owning component (backend/, frontend/) and keep cross-links minimal.
• Use consistent env var naming across backend and frontend; document once and link from both.
• Keep ADRs short: context, decision, consequences, and links to related ADRs.
• Prefer stable file names; avoid renames that break links.