From f68f354304bb4a09775671959d17a7c0bb27ddc4 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Fri, 26 Jun 2026 20:32:06 +0000 Subject: [PATCH 1/8] docs: add a write-docs authoring skill Add .claude/skills/write-docs/SKILL.md, the authoring counterpart to the doc-check skill. It points at docs/.style/content-guidelines.md as the canonical source for scope and routing, and at the prose style guide for formatting, then walks the authoring workflow: establish ground truth, decide whether content belongs in docs and where, pick the Diataxis mode and manifest slot, draft with discovery-based pedagogy, and validate. It carries the "what not to write" routing, Premium signaling, emdash, and rename and redirect guardrails. Cross-link the skill from both AGENTS.md navigation locations. Filed via Coder Agents on Nick's behalf. Refs: DOCS-364 --- .claude/skills/write-docs/SKILL.md | 179 +++++++++++++++++++++++++++++ AGENTS.md | 2 + 2 files changed, 181 insertions(+) create mode 100644 .claude/skills/write-docs/SKILL.md diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md new file mode 100644 index 00000000000..5ea430673c2 --- /dev/null +++ b/.claude/skills/write-docs/SKILL.md @@ -0,0 +1,179 @@ +--- +name: write-docs +description: Authoring workflow and guardrails for writing or editing Coder documentation under docs/. Points at the canonical content guidelines and prose style guide, then walks research, routing, Diataxis mode, structure, pedagogy, and validation. Counterpart to the doc-check skill, which reviews changes for documentation needs. +--- + +# Write Docs Skill + +Author or edit user-facing documentation under `docs/` so it is correct, +correctly scoped, and approvable in as few review cycles as possible. This is +the counterpart to the `doc-check` skill: `doc-check` decides whether a change +needs docs; this skill covers writing them well. + +> [!IMPORTANT] +> The **canonical** rules live outside this skill. Read them first; this skill +> only tells you how to apply them. +> +> - **Scope and routing** (does this belong in `docs/` at all, and where it +> goes if not): [`docs/.style/content-guidelines.md`](../../../docs/.style/content-guidelines.md). +> It governs on conflict. +> - **Prose and formatting:** the prose style guide at +> [`docs/.style/style-guide/`](../../../docs/.style/style-guide/README.md). +> Open it and apply it as a checklist. Do not write from memory; most style +> churn in review comes from rules that already exist but were not applied. +> - **Agent-facing structure and research notes:** +> [`.claude/docs/DOCS_STYLE_GUIDE.md`](../../docs/DOCS_STYLE_GUIDE.md). +> +> When this skill conflicts with the content guidelines, the content +> guidelines win. + +## Goal + +Most documentation review churn does not come from prose quality. It comes +from describing behavior that is wrong, content that does not belong in the +docs, or a page sequenced badly. This skill attacks those causes first, then +style. + +## Workflow + +1. **Establish ground truth before you write a sentence.** This is the + highest-leverage step and the one most often skipped. It is the practical + form of the content guidelines principle + [Verify against the code; document exact values](../../../docs/.style/content-guidelines.md#verify-against-the-code-document-exact-values). + - **Read the real source.** Open the actual template, config, code path, + or CLI definition. Copy exact identifiers, defaults, file paths, option + names, RBAC role names, thresholds, and API paths from the source, not + from memory. + - **Run the real thing.** Execute the commands in the same environment and + image the reader will use. Capture real output and real error strings. + Do not paraphrase an error you did not see. If you can only + source-verify a value, say so and flag it for the reviewer rather than + presenting a guess as fact. Programmatic content is a + [testable CI surface](../../../docs/.style/content-guidelines.md#programmatic-content-is-a-testable-ci-surface). + - **Learn the invariant.** For each behavioral claim, find the rule + underneath it, so you can explain *why*, not just *what*, and not write + something the maintainer knows is false. + - **Read the issue, linked tickets, and referenced PRs.** Real constraints + and intent often live there, not in the prose request. + - **Confirm integrations that already work.** Do not invent setup steps + for something the platform wires up for the user. When unsure whether a + step is required, test both paths or ask, rather than padding the guide. +2. **Decide whether it belongs in the docs, and where.** Walk the + [quick decision checklist](../../../docs/.style/content-guidelines.md#quick-decision-checklist). + If it does not belong, route it (see [What not to write](#what-not-to-write)). +3. **Pick the Diataxis mode and the manifest slot.** Choose one mode per page + (tutorial, how-to guide, reference, or explanation) per + the Diataxis framework in the [content guidelines](../../../docs/.style/content-guidelines.md). + One concept per page. New pages MUST be added to `docs/manifest.json` under + the right section, and the documentation lands in the same change as the + feature. +4. **Draft with deliberate pedagogy** (see patterns below). +5. **Self-review and validate.** Apply the prose style guide with it open. + Run `make lint/emdash`, markdownlint, and Vale. Run the commands and code + in the page. Fix every inbound link you moved and add redirects for any + rename (see [Renames and moves](#renames-and-moves)). + +## Pedagogy patterns + +- **Teach by discovery, but do not spoil the surprise.** A strong tutorial + has the reader do the thing, observe the result (including a failure), and + only then explains the mechanism and the fix. Front-loading the explanation + removes the reason the reader believes it. +- **Frame code as an instruction, not decoration.** Every code block should + answer "what do I do with this?" Prefer "Add this block to `main.tf`" over + dropping a block the reader must infer they should paste. Do not show code + for its own sake. +- **Keep full-file dumps out of the steps.** Inline only the diff the reader + applies. If a complete reference file helps, put it in a collapsed block at + the end, not in the middle of a step. +- **Respect the reader's tools.** Do not call a tool "the wrong fit" when it + works with configuration. Describe what it costs and how to make it work. +- **Minimize cross-page travel for one task.** A tutorial that sends the + reader to several other pages to finish a single task will be sent back. + Inline the happy path; link out for depth, not for required steps. +- **Mirror parallel paths.** If the product has a UI and a CLI, show both for + each step in a consistent structure so neither audience is stranded. + +## What not to write + +Do not put these in `docs/`. Route them per the +[routing table](../../../docs/.style/content-guidelines.md#routing-table). + +- **Predictive, timeless, or stale content.** Document only what applies to + the current version. Do not predict the future or carry forward material + that no longer applies. +- **Troubleshooting and failure-mode content.** Route to the support + knowledge base (Pylon); Support owns it. Docs own intended behavior. +- **Feature announcements and launch rationale ("why we built this").** + Route to the blog. Explaining how a feature is *supposed to work* is docs. +- **Duplicated third-party documentation** (Terraform, AWS, Microsoft, + Google, other vendors). Link to their docs; theirs is the source of truth. + The only exception is a minimal Terraform teaching example. +- **Contributing guides and style guides.** Keep with the code on GitHub. +- **Deep code internals.** Focus on inputs and outputs for the end user. +- **Known bugs whose intended behavior is not yet documented.** Route to the + changelog (document expected behavior only when Coder agrees the behavior + is wrong and the docs do not yet cover what should happen). + +## Premium feature signaling + +A page documenting a Premium feature needs **both**, or it is a defect: + +1. The H1 title takes a `(Premium)` suffix, for example + `# Template Insights (Premium)`. +2. The page's `docs/manifest.json` entry includes `"state": ["premium"]`. + +## Renames and moves + +1. Fix every inbound link to the old path. Choose the new target by intent, + the specific page the sentence promises, not just the section hub. A moved + section takes its anchor with it, so verify anchors still resolve. +2. Add a redirect in + [`coder/coder.com:redirects.json`](https://github.com/coder/coder.com/blob/master/redirects.json) + that maps the old public path to the new one, and open that PR alongside + the rename. Do not rely on a directory index resolving the old path, and + do not create a `docs/_redirects` file in this repo. + +## No emdash, endash, or `--` as punctuation + +This applies in prose, code blocks, comments, and string literals. Use +commas, semicolons, or periods, or restructure the sentence. For numeric +ranges use a plain hyphen (`0-100`). Enforced by `make lint/emdash`. + +## Anti-patterns observed in real review cycles + +- Describing behavior you did not verify (guessed error strings, assumed auth + flows, assumed persistence). The most expensive class of mistake. +- Code shown for its own sake, or a full file pasted into the middle of a + step. +- A tutorial that makes the reader hop across pages to finish one task. +- A correct but heavy-handed example that belongs in a different doc. +- Spoiling a discovery-based lesson by explaining the mechanism first. +- Telling the reader their tool is wrong when it merely needs configuration. +- Duplicating large content silently instead of flagging the maintenance + cost to the reviewer. +- Treating the style guide as optional recall instead of a checklist you open + and apply. + +## Pre-handoff checklist + +- [ ] Every factual claim is sourced from real code, a real run, or a linked + ticket, not from assumption. +- [ ] Commands and code in the page were executed, or explicitly flagged as + unverified for the reviewer. +- [ ] The content belongs in `docs/`; anything that does not was routed. +- [ ] One concept per page, correct Diataxis mode, added to + `docs/manifest.json`. +- [ ] Prose style guide applied with it open; `make lint/emdash`, + markdownlint, and Vale pass. +- [ ] Inbound links resolve; renames have redirects in `coder/coder.com`. +- [ ] Premium pages carry the title suffix and manifest state. +- [ ] Maintenance tradeoffs (duplication, unverified claims) are disclosed to + the reviewer, not hidden. + +## Feeding lessons back + +When a reviewer teaches a rule that is not yet in `docs/.style/`, add it there +in the same change set so the next author, human or model, starts from it +instead of rediscovering it in review. Shrinking review over time is the point +of this skill. diff --git a/AGENTS.md b/AGENTS.md index 988a81dcdd9..4a0da21bf77 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,7 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - Frontend: Read [Frontend Development Guidelines](site/AGENTS.md) before changing anything under `site/`. - Docs prose: When editing anything under `docs/`, refer to the prose style guide at [`docs/.style/style-guide/`](docs/.style/style-guide/README.md). For supporting agent-specific guidance, refer to [`.claude/docs/DOCS_STYLE_GUIDE.md`](.claude/docs/DOCS_STYLE_GUIDE.md), which covers structure, research, and content patterns. +- Writing docs: Before authoring or editing content under `docs/`, load the [`write-docs` skill](.claude/skills/write-docs/SKILL.md), which points at the canonical content guidelines and prose style guide, then walks research, routing, Diataxis mode, structure, and validation. ## Foundational rules @@ -221,6 +222,7 @@ manually before starting work: - `.claude/docs/TROUBLESHOOTING.md` - common failures and fixes (when stuck) - `.claude/docs/DOCS_STYLE_GUIDE.md` - docs prose and formatting (when writing `docs/`) - `docs/.style/content-guidelines.md` - canonical content scope and routing rules (when writing `docs/`; governs on conflicts with the style guide) +- `.claude/skills/write-docs/SKILL.md` - authoring workflow and guardrails (when writing or editing `docs/`) **For frontend work**, also read `site/AGENTS.md` before making any changes in `site/`. From 428a6ab43d1c9696eca09f07c24f96047006e5e3 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Fri, 26 Jun 2026 21:13:55 +0000 Subject: [PATCH 2/8] docs: link write-docs skill to canonical rules instead of restating them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address deep-review (coder-agents-review) Round 1 findings on the write-docs authoring skill: - CRF-1 (P2): replace the inline Premium, renames, and emdash restatements with one "Structural rules to apply" pointer to the canonical content-guidelines section, keeping only the rename application notes the canonical rules do not spell out. Removes the word-level divergences from doc-check present at merge time. - CRF-2/3/9: collapse "What not to write" to a pointer to the canonical exclusion catalog and routing table so the list cannot drift. This also stops dropping the known-bugs workaround clause and removes the reordered timeless/predictive wording, since nothing is restated. - CRF-4: correct "one concept per page" to the canonical "one outcome per page" in step 3 and the pre-handoff checklist. - CRF-5/7: rename the AGENTS.md nav entry to "Docs authoring" (noun phrase) and differentiate it from "Docs prose" by trigger (new or restructured pages vs prose-only edits). - CRF-6: restore the "Diátaxis" accent in all four occurrences. - CRF-8: normalize the read-when-relevant trigger to "(when writing docs/)". - Add a back-reference from doc-check to write-docs so the counterpart pairing is bidirectional. Refs: DOCS-364 Filed via Coder Agents on Nick's behalf. --- .claude/skills/doc-check/SKILL.md | 4 +- .claude/skills/write-docs/SKILL.md | 75 +++++++++++------------------- AGENTS.md | 6 +-- 3 files changed, 32 insertions(+), 53 deletions(-) diff --git a/.claude/skills/doc-check/SKILL.md b/.claude/skills/doc-check/SKILL.md index 2aef86c5b06..51d32f5a896 100644 --- a/.claude/skills/doc-check/SKILL.md +++ b/.claude/skills/doc-check/SKILL.md @@ -6,7 +6,9 @@ description: Checks if code changes require documentation updates # Documentation Check Skill Review code changes and determine if documentation updates or new -documentation is needed. +documentation is needed. This skill decides *whether* a change needs docs; +its counterpart, the [`write-docs` skill](../write-docs/SKILL.md), covers +writing them. > [!IMPORTANT] > The **canonical** rules for what belongs in the Coder docs (and what diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md index 5ea430673c2..b1fde7c4379 100644 --- a/.claude/skills/write-docs/SKILL.md +++ b/.claude/skills/write-docs/SKILL.md @@ -1,6 +1,6 @@ --- name: write-docs -description: Authoring workflow and guardrails for writing or editing Coder documentation under docs/. Points at the canonical content guidelines and prose style guide, then walks research, routing, Diataxis mode, structure, pedagogy, and validation. Counterpart to the doc-check skill, which reviews changes for documentation needs. +description: Authoring workflow and guardrails for writing or editing Coder documentation under docs/. Points at the canonical content guidelines and prose style guide, then walks research, routing, Diátaxis mode, structure, pedagogy, and validation. Counterpart to the doc-check skill, which reviews changes for documentation needs. --- # Write Docs Skill @@ -61,17 +61,17 @@ style. 2. **Decide whether it belongs in the docs, and where.** Walk the [quick decision checklist](../../../docs/.style/content-guidelines.md#quick-decision-checklist). If it does not belong, route it (see [What not to write](#what-not-to-write)). -3. **Pick the Diataxis mode and the manifest slot.** Choose one mode per page +3. **Pick the Diátaxis mode and the manifest slot.** Choose one mode per page (tutorial, how-to guide, reference, or explanation) per - the Diataxis framework in the [content guidelines](../../../docs/.style/content-guidelines.md). - One concept per page. New pages MUST be added to `docs/manifest.json` under + the Diátaxis framework in the [content guidelines](../../../docs/.style/content-guidelines.md). + One outcome per page. New pages MUST be added to `docs/manifest.json` under the right section, and the documentation lands in the same change as the feature. 4. **Draft with deliberate pedagogy** (see patterns below). 5. **Self-review and validate.** Apply the prose style guide with it open. Run `make lint/emdash`, markdownlint, and Vale. Run the commands and code in the page. Fix every inbound link you moved and add redirects for any - rename (see [Renames and moves](#renames-and-moves)). + rename (see [Structural rules to apply](#structural-rules-to-apply)). ## Pedagogy patterns @@ -96,49 +96,26 @@ style. ## What not to write -Do not put these in `docs/`. Route them per the -[routing table](../../../docs/.style/content-guidelines.md#routing-table). - -- **Predictive, timeless, or stale content.** Document only what applies to - the current version. Do not predict the future or carry forward material - that no longer applies. -- **Troubleshooting and failure-mode content.** Route to the support - knowledge base (Pylon); Support owns it. Docs own intended behavior. -- **Feature announcements and launch rationale ("why we built this").** - Route to the blog. Explaining how a feature is *supposed to work* is docs. -- **Duplicated third-party documentation** (Terraform, AWS, Microsoft, - Google, other vendors). Link to their docs; theirs is the source of truth. - The only exception is a minimal Terraform teaching example. -- **Contributing guides and style guides.** Keep with the code on GitHub. -- **Deep code internals.** Focus on inputs and outputs for the end user. -- **Known bugs whose intended behavior is not yet documented.** Route to the - changelog (document expected behavior only when Coder agrees the behavior - is wrong and the docs do not yet cover what should happen). - -## Premium feature signaling - -A page documenting a Premium feature needs **both**, or it is a defect: - -1. The H1 title takes a `(Premium)` suffix, for example - `# Template Insights (Premium)`. -2. The page's `docs/manifest.json` entry includes `"state": ["premium"]`. - -## Renames and moves - -1. Fix every inbound link to the old path. Choose the new target by intent, - the specific page the sentence promises, not just the section hub. A moved - section takes its anchor with it, so verify anchors still resolve. -2. Add a redirect in - [`coder/coder.com:redirects.json`](https://github.com/coder/coder.com/blob/master/redirects.json) - that maps the old public path to the new one, and open that PR alongside - the rename. Do not rely on a directory index resolving the old path, and - do not create a `docs/_redirects` file in this repo. - -## No emdash, endash, or `--` as punctuation - -This applies in prose, code blocks, comments, and string literals. Use -commas, semicolons, or periods, or restructure the sentence. For numeric -ranges use a plain hyphen (`0-100`). Enforced by `make lint/emdash`. +Do not put non-docs content in `docs/`. The canonical catalog of what to +exclude, where each item goes, and why is +[What does not belong in the docs](../../../docs/.style/content-guidelines.md#what-does-not-belong-in-the-docs) +plus the [routing table](../../../docs/.style/content-guidelines.md#routing-table). +Check it before adding a page. Do not reproduce the catalog here, so it cannot +drift from the source. + +## Structural rules to apply + +The canonical +[Structural rules](../../../docs/.style/content-guidelines.md#structural-rules) +cover the manifest entry, Premium marking, renames and redirects, and the +emdash ban. Read them for the exact wording; the pre-handoff checklist below +turns them into pass/fail items. Two application notes the canonical rules do +not spell out: + +- On a rename, pick the new link target by the specific page each sentence + promises, not just the section hub, and confirm moved anchors still resolve. +- Keep the redirect PR in `coder/coder.com` in sync with the rename PR so the + old public path never 404s between merges. ## Anti-patterns observed in real review cycles @@ -162,7 +139,7 @@ ranges use a plain hyphen (`0-100`). Enforced by `make lint/emdash`. - [ ] Commands and code in the page were executed, or explicitly flagged as unverified for the reviewer. - [ ] The content belongs in `docs/`; anything that does not was routed. -- [ ] One concept per page, correct Diataxis mode, added to +- [ ] One outcome per page, correct Diátaxis mode, added to `docs/manifest.json`. - [ ] Prose style guide applied with it open; `make lint/emdash`, markdownlint, and Vale pass. diff --git a/AGENTS.md b/AGENTS.md index 4a0da21bf77..85cdd4c10f6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,9 +12,9 @@ Rule #1: If you want exception to ANY rule, YOU MUST STOP and get explicit permi - Docs content scope: Use [Coder Docs Content Guidelines](docs/.style/content-guidelines.md) to decide whether a piece of content belongs in `docs/` at all. The Documentation Style Guide above covers prose and formatting; the content guidelines govern scope and routing and supersede the style guide on conflicts. - Compatibility: `.agents/docs` symlinks to `.claude/docs` for agent runtimes that look there. - Frontend: Read [Frontend Development Guidelines](site/AGENTS.md) before changing anything under `site/`. -- Docs prose: When editing anything under `docs/`, refer to the prose style guide at [`docs/.style/style-guide/`](docs/.style/style-guide/README.md). +- Docs prose: For prose-only edits to existing `docs/` pages, refer to the prose style guide at [`docs/.style/style-guide/`](docs/.style/style-guide/README.md). For supporting agent-specific guidance, refer to [`.claude/docs/DOCS_STYLE_GUIDE.md`](.claude/docs/DOCS_STYLE_GUIDE.md), which covers structure, research, and content patterns. -- Writing docs: Before authoring or editing content under `docs/`, load the [`write-docs` skill](.claude/skills/write-docs/SKILL.md), which points at the canonical content guidelines and prose style guide, then walks research, routing, Diataxis mode, structure, and validation. +- Docs authoring: For new, moved, or restructured `docs/` pages, or when unsure, load the [`write-docs` skill](.claude/skills/write-docs/SKILL.md) first. It points at the canonical content guidelines and the prose style guide above, then walks research, routing, Diátaxis mode, structure, and validation. ## Foundational rules @@ -222,7 +222,7 @@ manually before starting work: - `.claude/docs/TROUBLESHOOTING.md` - common failures and fixes (when stuck) - `.claude/docs/DOCS_STYLE_GUIDE.md` - docs prose and formatting (when writing `docs/`) - `docs/.style/content-guidelines.md` - canonical content scope and routing rules (when writing `docs/`; governs on conflicts with the style guide) -- `.claude/skills/write-docs/SKILL.md` - authoring workflow and guardrails (when writing or editing `docs/`) +- `.claude/skills/write-docs/SKILL.md` - authoring workflow and guardrails (when writing `docs/`) **For frontend work**, also read `site/AGENTS.md` before making any changes in `site/`. From 91d6539993e0ca07fc53481d130263b3b9681ee6 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Fri, 26 Jun 2026 21:37:52 +0000 Subject: [PATCH 3/8] docs: align write-docs skill heading, link, and nav trigger MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address deep-review (coder-agents-review) Round 2 nits (PR already approved, no blockers): - CRF-10: rename the H1 to "Documentation Authoring Skill" (noun phrase), matching the sibling "Documentation Check Skill" convention. - CRF-11: add the "#follow-the-diátaxis-framework" anchor to the step 3 content-guidelines link, consistent with the other cross-file links. - CRF-12: scope the read-when-relevant trigger to "for new or restructured docs/ pages" so it matches the nav routing. Refs: DOCS-364 Filed via Coder Agents on Nick's behalf. --- .claude/skills/write-docs/SKILL.md | 4 ++-- AGENTS.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md index b1fde7c4379..a2d55342c1f 100644 --- a/.claude/skills/write-docs/SKILL.md +++ b/.claude/skills/write-docs/SKILL.md @@ -3,7 +3,7 @@ name: write-docs description: Authoring workflow and guardrails for writing or editing Coder documentation under docs/. Points at the canonical content guidelines and prose style guide, then walks research, routing, Diátaxis mode, structure, pedagogy, and validation. Counterpart to the doc-check skill, which reviews changes for documentation needs. --- -# Write Docs Skill +# Documentation Authoring Skill Author or edit user-facing documentation under `docs/` so it is correct, correctly scoped, and approvable in as few review cycles as possible. This is @@ -63,7 +63,7 @@ style. If it does not belong, route it (see [What not to write](#what-not-to-write)). 3. **Pick the Diátaxis mode and the manifest slot.** Choose one mode per page (tutorial, how-to guide, reference, or explanation) per - the Diátaxis framework in the [content guidelines](../../../docs/.style/content-guidelines.md). + the Diátaxis framework in the [content guidelines](../../../docs/.style/content-guidelines.md#follow-the-diátaxis-framework). One outcome per page. New pages MUST be added to `docs/manifest.json` under the right section, and the documentation lands in the same change as the feature. diff --git a/AGENTS.md b/AGENTS.md index 85cdd4c10f6..9984636f06d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -222,7 +222,7 @@ manually before starting work: - `.claude/docs/TROUBLESHOOTING.md` - common failures and fixes (when stuck) - `.claude/docs/DOCS_STYLE_GUIDE.md` - docs prose and formatting (when writing `docs/`) - `docs/.style/content-guidelines.md` - canonical content scope and routing rules (when writing `docs/`; governs on conflicts with the style guide) -- `.claude/skills/write-docs/SKILL.md` - authoring workflow and guardrails (when writing `docs/`) +- `.claude/skills/write-docs/SKILL.md` - authoring workflow and guardrails (for new or restructured `docs/` pages) **For frontend work**, also read `site/AGENTS.md` before making any changes in `site/`. From 48a5cfd3d5e9da19983f1e5f1e78d9dba2151dbd Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Fri, 26 Jun 2026 22:00:01 +0000 Subject: [PATCH 4/8] docs: restore "moved" trigger and complete the structural-rules list Address deep-review (coder-agents-review) Round 3: - CRF-13 (P3): restore "moved" to the read-when-relevant trigger so it matches the nav routing ("new, moved, or restructured docs/ pages") and the skill's own page-move guidance. Fixes a scope regression from the Round 2 CRF-12 fix. - CRF-14 (Note): add "auto-generated content" to the structural-rules summary so the enumeration covers all five canonical rules. Refs: DOCS-364 Filed via Coder Agents on Nick's behalf. --- .claude/skills/write-docs/SKILL.md | 8 ++++---- AGENTS.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md index a2d55342c1f..3be217f76f6 100644 --- a/.claude/skills/write-docs/SKILL.md +++ b/.claude/skills/write-docs/SKILL.md @@ -107,10 +107,10 @@ drift from the source. The canonical [Structural rules](../../../docs/.style/content-guidelines.md#structural-rules) -cover the manifest entry, Premium marking, renames and redirects, and the -emdash ban. Read them for the exact wording; the pre-handoff checklist below -turns them into pass/fail items. Two application notes the canonical rules do -not spell out: +cover the manifest entry, auto-generated content, Premium marking, renames +and redirects, and the emdash ban. Read them for the exact wording; the +pre-handoff checklist below turns them into pass/fail items. Two application +notes the canonical rules do not spell out: - On a rename, pick the new link target by the specific page each sentence promises, not just the section hub, and confirm moved anchors still resolve. diff --git a/AGENTS.md b/AGENTS.md index 9984636f06d..42ddfe71f65 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -222,7 +222,7 @@ manually before starting work: - `.claude/docs/TROUBLESHOOTING.md` - common failures and fixes (when stuck) - `.claude/docs/DOCS_STYLE_GUIDE.md` - docs prose and formatting (when writing `docs/`) - `docs/.style/content-guidelines.md` - canonical content scope and routing rules (when writing `docs/`; governs on conflicts with the style guide) -- `.claude/skills/write-docs/SKILL.md` - authoring workflow and guardrails (for new or restructured `docs/` pages) +- `.claude/skills/write-docs/SKILL.md` - authoring workflow and guardrails (for new, moved, or restructured `docs/` pages) **For frontend work**, also read `site/AGENTS.md` before making any changes in `site/`. From 2236ecff2ffde224fa8d4d822de3d486226051a3 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Sat, 27 Jun 2026 00:27:42 +0000 Subject: [PATCH 5/8] docs: add maintenance-burden, screenshot, and series-nav guidance to write-docs Lessons from the Quickstart review (Ben Potter, Kayla): - Prefer the lowest-maintenance correct presentation; brittle references (hard-coded line numbers, screenshots of copyable text) rot. A screenshot still earns its place when a UI step genuinely needs it; weigh the upkeep, and flag the gap if you cannot capture one rather than omitting it silently or treating "no screenshot" as policy. - Orient the reader inside a multi-page series; never ship a dead-end page. Added a matching pre-handoff checklist item. Refs: DOCS-364 Filed via Coder Agents on Nick's behalf. --- .claude/skills/write-docs/SKILL.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md index 3be217f76f6..5051996d0c3 100644 --- a/.claude/skills/write-docs/SKILL.md +++ b/.claude/skills/write-docs/SKILL.md @@ -93,6 +93,16 @@ style. Inline the happy path; link out for depth, not for required steps. - **Mirror parallel paths.** If the product has a UI and a CLI, show both for each step in a consistent structure so neither audience is stranded. +- **Show the truth in its lowest-maintenance form.** When two correct + presentations exist, prefer the one that ages best. A hard-coded line number + or a screenshot of text reads fine today and rots when the source changes. A + screenshot still earns its place when a UI step genuinely needs to be seen; + weigh the upkeep, and if you cannot capture one, flag the gap rather than + omit it silently or treat "no screenshot" as a policy. +- **Orient the reader inside a series.** A multi-page series must say where the + reader is and what comes next. End each page with a consistent next step (and + Previous/Next where the engine supports it); never ship a page that + dead-ends. ## What not to write @@ -127,6 +137,8 @@ notes the canonical rules do not spell out: - A correct but heavy-handed example that belongs in a different doc. - Spoiling a discovery-based lesson by explaining the mechanism first. - Telling the reader their tool is wrong when it merely needs configuration. +- Brittle references that rot: hard-coded line numbers, or a screenshot + standing in for text the reader could copy. - Duplicating large content silently instead of flagging the maintenance cost to the reviewer. - Treating the style guide as optional recall instead of a checklist you open @@ -145,6 +157,7 @@ notes the canonical rules do not spell out: markdownlint, and Vale pass. - [ ] Inbound links resolve; renames have redirects in `coder/coder.com`. - [ ] Premium pages carry the title suffix and manifest state. +- [ ] Series pages orient the reader and link the next step; no dead-ends. - [ ] Maintenance tradeoffs (duplication, unverified claims) are disclosed to the reviewer, not hidden. From a51ea02c264ee75b7d146341bfd62ebbce72978f Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Sat, 27 Jun 2026 01:05:15 +0000 Subject: [PATCH 6/8] docs: match write-docs description to nav routing scope Change the frontmatter description from "writing or editing" to "writing, moving, or restructuring" so the skills registry indexes on a scope that matches the AGENTS.md routing ("new, moved, or restructured docs/ pages, or when unsure"). This avoids signaling capability for prose-only edits that AGENTS.md deliberately routes to the simpler prose style guide. Refs: DOCS-364 Filed via Coder Agents on Nick's behalf. --- .claude/skills/write-docs/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md index 5051996d0c3..ef8347f0f89 100644 --- a/.claude/skills/write-docs/SKILL.md +++ b/.claude/skills/write-docs/SKILL.md @@ -1,6 +1,6 @@ --- name: write-docs -description: Authoring workflow and guardrails for writing or editing Coder documentation under docs/. Points at the canonical content guidelines and prose style guide, then walks research, routing, Diátaxis mode, structure, pedagogy, and validation. Counterpart to the doc-check skill, which reviews changes for documentation needs. +description: Authoring workflow and guardrails for writing, moving, or restructuring Coder documentation under docs/. Points at the canonical content guidelines and prose style guide, then walks research, routing, Diátaxis mode, structure, pedagogy, and validation. Counterpart to the doc-check skill, which reviews changes for documentation needs. --- # Documentation Authoring Skill From ba4bd80609e6a24180ced3e943e1f4272d58ec60 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Sat, 27 Jun 2026 01:27:24 +0000 Subject: [PATCH 7/8] docs: advise keeping doc PRs reviewable (~1,000 lines max) Add a "Keep PRs reviewable" guardrail and a pre-handoff checklist item to the write-docs skill: keep each docs PR focused, ideally under ~1,000 lines changed, and split a multi-page series into one-page-per-PR changes. Large diffs get rubber-stamped or bounced, and both cost more review cycles than splitting up front. Refs: DOCS-364 Filed via Coder Agents on Nick's behalf. --- .claude/skills/write-docs/SKILL.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md index ef8347f0f89..931ff556799 100644 --- a/.claude/skills/write-docs/SKILL.md +++ b/.claude/skills/write-docs/SKILL.md @@ -127,6 +127,15 @@ notes the canonical rules do not spell out: - Keep the redirect PR in `coder/coder.com` in sync with the rename PR so the old public path never 404s between merges. +## Keep PRs reviewable + +Large diffs get worse reviews. A reviewer who cannot hold the whole change in +their head will either rubber-stamp it or bounce it, and both cost more cycles +than splitting up front. Keep each docs PR focused, ideally under ~1,000 lines +changed whenever possible. For a multi-page series, prefer one page (or one +tightly scoped change) per PR, and stack or sequence them rather than shipping +the whole series as a single review. + ## Anti-patterns observed in real review cycles - Describing behavior you did not verify (guessed error strings, assumed auth @@ -158,6 +167,9 @@ notes the canonical rules do not spell out: - [ ] Inbound links resolve; renames have redirects in `coder/coder.com`. - [ ] Premium pages carry the title suffix and manifest state. - [ ] Series pages orient the reader and link the next step; no dead-ends. +- [ ] The change is scoped for review: large or multi-page work is split into + focused PRs (aim for under ~1,000 lines changed; one page per PR for a + series). - [ ] Maintenance tradeoffs (duplication, unverified claims) are disclosed to the reviewer, not hidden. From 2ceca0a3890feeae0c1ae3db0e5f4adfc20e85d4 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Wed, 8 Jul 2026 12:01:40 -0400 Subject: [PATCH 8/8] docs: link write-docs skill to the PR description style guide Addresses review feedback on #26767: add a Workflow step and a pre-handoff checklist item that point at .claude/docs/PR_STYLE_GUIDE.md for PR title/description format and the draft vs. ready-for-review convention, instead of restating those rules in the skill. > Generated by Coder Agents on behalf of @nickvigilante. --- .claude/skills/write-docs/SKILL.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md index 931ff556799..c146d45bf46 100644 --- a/.claude/skills/write-docs/SKILL.md +++ b/.claude/skills/write-docs/SKILL.md @@ -72,6 +72,10 @@ style. Run `make lint/emdash`, markdownlint, and Vale. Run the commands and code in the page. Fix every inbound link you moved and add redirects for any rename (see [Structural rules to apply](#structural-rules-to-apply)). +6. **Open the PR.** Write the title and description per the + [Pull Request Description Style Guide](../../docs/PR_STYLE_GUIDE.md), which + also covers when to open as a draft and when to mark it ready for review. + Keep the diff reviewable (see [Keep PRs reviewable](#keep-prs-reviewable)). ## Pedagogy patterns @@ -170,6 +174,8 @@ the whole series as a single review. - [ ] The change is scoped for review: large or multi-page work is split into focused PRs (aim for under ~1,000 lines changed; one page per PR for a series). +- [ ] PR title and description follow the PR description style guide (including + draft vs. ready-for-review). - [ ] Maintenance tradeoffs (duplication, unverified claims) are disclosed to the reviewer, not hidden.