docs-update-from-diff

Docs Update From Diff

Overview

Inspect local diffs, derive the documentation impact, and update only the repository's docs/ pages. Treat the current code as the source of truth and keep changes scoped, specific, and navigable.

Read references/docs-surface.md before editing if the affected feature does not map cleanly to an existing docs section.

Workflow

1. Build the change set

Start from local Git state, not from assumptions.

• Inspect git status --short, git diff --stat, and targeted git diff output.
• Focus on non-doc changes first so the documentation delta is grounded in code.
• Ignore README.md and other non-docs/ content unless they help confirm intent.

2. Derive the docs impact

For every changed behavior, extract the user-facing or developer-facing facts that documentation must reflect.

• New command, flag, config key, default, workflow, or limitation
• Renamed behavior or removed behavior
• Changed examples, paths, or setup steps
• New feature that belongs in an existing page but is not mentioned yet

Prefer updating an existing page over creating a new page. Create a new page only when the feature introduces a stable topic that would make an existing page harder to follow.

3. Find the right docs location

Map each change to the smallest correct documentation surface:

• End-user behavior: docs/users/**
• Developer internals, SDKs, contributor workflow, tooling: docs/developers/**
• Shared landing or navigation changes: root docs/** and _meta.ts

If you add a new page, update the nearest _meta.ts in the same docs section so the page is discoverable.

4. Write the update

Edit documentation with the following bar:

• State the current behavior, not the implementation history
• Use concrete commands, file paths, setting keys, and defaults from the diff
• Remove or rewrite stale text instead of stacking caveats on top of it
• Keep examples aligned with the current CLI and repository layout
• Preserve the repository's existing docs tone and heading structure