From 045b138c014158c16174405c163a6bc3e2295dca Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 21 Jul 2026 11:09:09 -0500 Subject: [PATCH 1/8] docs enablement first attempt --- .claude/commands/docs/review-doc.md | 36 +++++++++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 16 +++++++++ CLAUDE.md | 54 +++++++++++++++++++++++++++++ CONTRIBUTING.md | 48 +++++++++++++++++++++++++ archetypes/concept.md | 36 +++++++++++++++++++ archetypes/reference.md | 38 ++++++++++++++++++++ archetypes/task.md | 48 +++++++++++++++++++++++++ docs-definition-of-done.md | 28 +++++++++++++++ 8 files changed, 304 insertions(+) create mode 100644 .claude/commands/docs/review-doc.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CLAUDE.md create mode 100644 CONTRIBUTING.md create mode 100644 archetypes/concept.md create mode 100644 archetypes/reference.md create mode 100644 archetypes/task.md create mode 100644 docs-definition-of-done.md diff --git a/.claude/commands/docs/review-doc.md b/.claude/commands/docs/review-doc.md new file mode 100644 index 0000000000..fb82047585 --- /dev/null +++ b/.claude/commands/docs/review-doc.md @@ -0,0 +1,36 @@ +--- +description: Self-review a docs change against the style rubric + deterministic gates before opening a PR +argument-hint: (no args — reviews changed docs on the current branch) +--- + + + +# /docs:review-doc — self-review before you open a PR + +Purpose: a contributor runs this on their changed docs so problems get caught *before* a human review — keeping the docs-team gate fast. + +## What it checks + +**Deterministic (wire to existing tooling):** +- **Vale** — style + terminology, on changed files only +- **Links** — relref / shortcode paths resolve (reuse the shortcode-path hook) +- **Build** — `hugo` builds clean +- **Frontmatter** — present + complete: `title`, `linkTitle`, `description`, `weight`, `categories` + +**AI rubric (the judgment layer — the part that needs a model):** +- **Voice:** addresses "you," active voice, present tense; no marketing words ("seamless," "powerful," "simply") +- **Structure:** matches the template shape for the doc type; sentence-case headings; verb-first task titles; one action per step +- **Coverage / IA:** does this duplicate or belong inside an existing page? → suggest fold-in or cross-links +- **Placeholders & security:** code uses `` placeholders; no real credentials, PII, IPs, or keys +- **Minimalism:** flag intro fluff, redundancy, and jargon + +## Output +A per-item checklist (pass / fix), each fix with a line pointer and a concrete suggestion, ending with a **"ready for review?"** verdict. + +## Mechanics (teammate lane — stub, design freely) +- Scope to changed files via `git diff` (the `/edit` skill already does this — reuse it). +- Model: per the plan's model strategy (Opus for the rubric gate; Haiku for the deterministic pass). +- Follows Andy's `/docs:*` command pattern. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..175ef93b73 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,16 @@ +## Summary + + + +## Docs checklist + +- [ ] **Coverage checked** — extended or cross-linked existing docs where possible (no orphan or duplicate page) +- [ ] Used the right **template** (task / concept / reference) +- [ ] **Frontmatter complete** and the page **builds clean** (CI) +- [ ] **Technically accurate** +- [ ] Follows the [style conventions](../CLAUDE.md) + + +- [ ] **No docs needed** (no user-facing change) + +New to contributing docs? See [CONTRIBUTING.md](../CONTRIBUTING.md). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..de071bad49 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,54 @@ +# Redis docs — writing conventions (humans + AI) + +Base style: **Google developer documentation style**; fall back to the **Microsoft Writing Style Guide** where Google is silent. Follow these on every docs change. AI tools working in this repo inherit these rules automatically. + +## Voice & tone + +- Address the reader as **"you."** Use **present tense** and **active voice**. +- Be direct and friendly. **No marketing tone** — avoid "best-in-class," "seamless," "powerful," "simply," "just," "easily." +- **Minimalism:** cut intro fluff, get to the action, say what's needed and stop. + +## Structure + +- **Sentence-case headings** ("Configure a database," not "Configure A Database"). +- **Task/procedure titles start with a verb** ("Create a role," "Enable auditing"). +- Follow the reader's **real workflow, in order.** Number sequential steps; **one action per step.** +- Don't stack notes back-to-back. **No directional language** ("above/below/on the left") — link to the thing instead. + +## Terminology & accessible language + +- Use official **product / feature / UI names** exactly. +- Prefer plain, inclusive terms: **replica** (not slave/master), **turn off** (not disable), **end** (not kill), **allowlist/denylist**. +- Spell out an acronym on first use. + +## Links + +- **Descriptive link text** ("see the [database configuration reference]") — never "click here" or a bare URL. +- Internal links use the relref shortcode: `{{< relref "/operate/rs/..." >}}`. + +## Frontmatter (every page) + +```yaml +--- +title: +linkTitle: +description: +weight: +categories: [docs, operate] # match the section +--- +``` + +## Coverage-aware authoring — do this FIRST + +- Before creating a page, **check whether the topic already exists.** Prefer to **fold into / extend / cross-link** an existing page over making a new one. +- Create a new page only when it's genuinely new — and **never leave it orphaned**: link it from its section index. + +## Code & security + +- In code and command examples, use **angle-bracket placeholders** — `` — never real values. (This is the one exception to "match the UI exactly.") +- **Never** include real credentials, PII, customer IPs, or SSH keys. + +## Before opening a PR + +- Run the self-check (`/docs:review-doc` once it exists); at minimum run **Vale**, the **link check**, and a **Hugo build**. +- Confirm frontmatter is complete and the page is linked from its section. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..d97330b049 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,48 @@ +# Contributing to Redis docs + +Thanks for helping keep our docs accurate and useful. Docs are part of a feature's definition of done — this guide is everything you need to contribute with minimal friction. + +> **Fastest path:** check for an existing page → copy a template → draft with AI in the repo (it already knows our style) → run the self-check → open a PR. Details below. + +## Do I need to write docs for this change? + +- **No user-facing change** (refactor, internal, tests, CI) → **no docs.** Note "no docs needed" on your PR. +- **New feature, behavior, or setting** → **yes** — a short task or concept page. +- **New or changed API / config field** → **update the reference** (often auto-generated — check with the docs team first). + +Full policy: [Definition of Done: Docs](./docs-definition-of-done.md). When unsure, ask in **[#docs channel]** — a 30-second question beats a missed page. + +## The golden path + +1. **Check what exists.** Search the docs for your topic; if there's a related page, add to it instead of creating a new one. +2. **Copy the template** for your doc type from `archetypes/` (`task` / `concept` / `reference`), or run `hugo new content//.md --kind task`. +3. **Draft with AI in the repo.** Claude inherits our style from the committed `CLAUDE.md` — give it your notes and ask it to draft in our conventions. +4. **Self-check.** Run `/docs:review-doc` (or at least Vale + the link check + a local `hugo` build) and fix what it flags. +5. **Open a PR** and fill the docs checklist. A docs teammate reviews for voice and structure, then merges. + +## Templates + +Per-type starting points live in **`archetypes/`**: `task` (how-to), `concept` (what/why), `reference` (fields/options). Each has inline guidance — delete the comments before publishing. + +## Style + +We follow Google developer style. The full rules live in the committed **`CLAUDE.md`**, so AI drafting in the repo inherits them automatically. The short version: write to "you," active voice, present tense; sentence-case headings; verb-first task titles; angle-bracket `` in code; descriptive link text; no marketing language. + +## What makes a PR ready for review (the bar) + +A docs teammate edits *from* your draft — they can't rewrite it from scratch. Before you request review, make sure it: + +- [ ] Uses the right **template** (structure is there) +- [ ] Is **placed sensibly** — folded into or cross-linked with related docs, not an orphan or duplicate +- [ ] **Builds clean**, with complete frontmatter (CI will tell you) +- [ ] Is **technically accurate — and you've tested it** (followed the steps / ran the commands / checked the output), not just written it — the part only you can guarantee + +If it's missing these, we'll send it back with a pointer — not to be difficult, but because that bar is what lets a small docs team keep up. + +## Who owns what + +**You** own technical accuracy and a solid first draft. **The docs team** owns voice, structure, and where it lives in the docs. + +## Getting help + +Ask in **[#docs channel]**, or tag a docs teammate on your PR. diff --git a/archetypes/concept.md b/archetypes/concept.md new file mode 100644 index 0000000000..fa50983218 --- /dev/null +++ b/archetypes/concept.md @@ -0,0 +1,36 @@ +--- +title: "" +linkTitle: "" +description: "" +weight: 10 +categories: ["docs", "operate"] +--- + + + +One or two sentences: what this is and why the reader should care. + +## How it works + + + +## + + + +## When to use it + + + +## Related + + + +- []({{< relref "/operate/..." >}}) +- []({{< relref "/operate/..." >}}) diff --git a/archetypes/reference.md b/archetypes/reference.md new file mode 100644 index 0000000000..2d52eeb155 --- /dev/null +++ b/archetypes/reference.md @@ -0,0 +1,38 @@ +--- +title: "" +linkTitle: "" +description: "" +weight: 10 +categories: ["docs", "operate", "reference"] +--- + + + +One sentence on what this reference covers and where it applies. + +## + +| Name | Type | Default | Description | +|------|------|---------|-------------| +| `` | `` | `` | | +| `` | `` | `` | <...> | + +## Syntax + + + +```sh + -- +``` + +## Related + +- []({{< relref "/operate/..." >}}) +- []({{< relref "/operate/..." >}}) diff --git a/archetypes/task.md b/archetypes/task.md new file mode 100644 index 0000000000..950a6d5f70 --- /dev/null +++ b/archetypes/task.md @@ -0,0 +1,48 @@ +--- +title: "" +linkTitle: "" +description: "" +weight: 10 +categories: ["docs", "operate"] +--- + + + +Brief intro — 1–2 sentences on what this task does and when you'd do it. No history or marketing. + +## Prerequisites + + + +- +- + +## + + + +1. + + ```sh + + ``` + +2. + +## Verify + + + + + +## Next steps + + + +- []({{< relref "/operate/..." >}}) diff --git a/docs-definition-of-done.md b/docs-definition-of-done.md new file mode 100644 index 0000000000..70b116d37d --- /dev/null +++ b/docs-definition-of-done.md @@ -0,0 +1,28 @@ +# Definition of Done: Docs + +"Docs are part of the definition of done" — here's what that concretely means, scaled to the size of the change so it's realistic. + +A change is **docs-done** when the matching row is satisfied: + +| Change type | What's required | +|---|---| +| No user-facing impact (refactor, internal, tests, CI) | Assert **"no docs needed"** on the PR. | +| New or changed user-facing **feature, behavior, setting, or default** | A **docs PR** — a task or concept page from the template, meeting the contribution bar, **tested (steps/commands actually run)**. | +| New or changed **API, CRD, or config field** | The relevant **reference updated** (often auto-generated — coordinate with docs). | +| **Deprecation or removal** | A **release-note entry** + affected pages updated. | + +## How it's enforced (engineering-owned, not docs-policed) +- **PR template** docs checklist — self-attested by the author. +- **Eng lead** confirms at PR review / sprint close. +- **Docs team provides** the templates, style, tooling, and final review — *not* enforcement. (If docs chases every PR, the bottleneck just moves.) + +## The bar for a docs PR +See [CONTRIBUTING.md](./CONTRIBUTING.md) — template used, placed coverage-aware, builds clean, technically accurate. + +## Division of labor +**Author** owns technical accuracy + a solid first draft. **Docs team** owns voice, structure, and placement. + +## Open for leadership / eng leads +- Ratify this definition and **re-broadcast it with these specifics** (the original message lacked them). +- Agree **where the tripwire lives**: PR-template checkbox (light) vs. a merge gate (strict). +- Confirm the change-type rows match how teams actually ship. From 55554bbd8fcc9a9643509643524983e0eda99833 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 21 Jul 2026 17:46:27 -0500 Subject: [PATCH 2/8] add agents file --- AGENTS.md | 5 +++++ CLAUDE.md | 5 ++++- CONTRIBUTING.md | 4 ++-- 3 files changed, 11 insertions(+), 3 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..9af1ac4db9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,5 @@ +# AGENTS.md + +This repo's writing conventions for AI tools live in [CLAUDE.md](./CLAUDE.md). Codex and any other agent working here should read and follow it — it's the same base style (Google developer documentation style), voice, structure, terminology, frontmatter, and coverage-aware authoring rules that human contributors follow. + +For the contributor workflow (golden path, templates, self-check, the PR bar), see [CONTRIBUTING.md](./CONTRIBUTING.md). diff --git a/CLAUDE.md b/CLAUDE.md index de071bad49..c1a5e80300 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,7 +17,10 @@ Base style: **Google developer documentation style**; fall back to the **Microso ## Terminology & accessible language -- Use official **product / feature / UI names** exactly. +- Use official **product / feature / UI names** exactly. The ones writers most often get wrong: + - **Redis Software** (standalone) and **Redis Software for Kubernetes** (the operator-based product) — not "Redis Enterprise" in prose. + - **Redis Feature Form** on first use per page, then **Feature Form** — never "Featureform." + - In prose, write **databases**, not "BDB"/"BDBs." The literal `bdb` API value and the `REC`/`REDB` abbreviations stay as-is, and CRD identifiers (`RedisEnterpriseCluster`, `RedisEnterpriseDatabase`, `RedisEnterpriseUser`) keep their exact casing. - Prefer plain, inclusive terms: **replica** (not slave/master), **turn off** (not disable), **end** (not kill), **allowlist/denylist**. - Spell out an acronym on first use. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d97330b049..d502fb5bb0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ Thanks for helping keep our docs accurate and useful. Docs are part of a feature - **New feature, behavior, or setting** → **yes** — a short task or concept page. - **New or changed API / config field** → **update the reference** (often auto-generated — check with the docs team first). -Full policy: [Definition of Done: Docs](./docs-definition-of-done.md). When unsure, ask in **[#docs channel]** — a 30-second question beats a missed page. +Full policy: [Definition of Done: Docs](./docs-definition-of-done.md). When unsure, ask in **#ask-docs** — a 30-second question beats a missed page. ## The golden path @@ -45,4 +45,4 @@ If it's missing these, we'll send it back with a pointer — not to be difficult ## Getting help -Ask in **[#docs channel]**, or tag a docs teammate on your PR. +Ask in **#ask-docs**, or tag a docs teammate on your PR. From 6712f023db30f10bff0b8588bb552f65073a658b Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Tue, 21 Jul 2026 18:09:58 -0500 Subject: [PATCH 3/8] walkthrough --- CONTRIBUTING.md | 2 +- .../docs-definition-of-done.md | 2 +- docs-enablement/enablement-walkthrough.md | 85 +++++++++++++++++++ 3 files changed, 87 insertions(+), 2 deletions(-) rename docs-definition-of-done.md => docs-enablement/docs-definition-of-done.md (93%) create mode 100644 docs-enablement/enablement-walkthrough.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d502fb5bb0..2ba42e92a4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ Thanks for helping keep our docs accurate and useful. Docs are part of a feature - **New feature, behavior, or setting** → **yes** — a short task or concept page. - **New or changed API / config field** → **update the reference** (often auto-generated — check with the docs team first). -Full policy: [Definition of Done: Docs](./docs-definition-of-done.md). When unsure, ask in **#ask-docs** — a 30-second question beats a missed page. +Full policy: [Definition of Done: Docs](./docs-enablement/docs-definition-of-done.md). When unsure, ask in **#ask-docs** — a 30-second question beats a missed page. ## The golden path diff --git a/docs-definition-of-done.md b/docs-enablement/docs-definition-of-done.md similarity index 93% rename from docs-definition-of-done.md rename to docs-enablement/docs-definition-of-done.md index 70b116d37d..a30c435a3b 100644 --- a/docs-definition-of-done.md +++ b/docs-enablement/docs-definition-of-done.md @@ -17,7 +17,7 @@ A change is **docs-done** when the matching row is satisfied: - **Docs team provides** the templates, style, tooling, and final review — *not* enforcement. (If docs chases every PR, the bottleneck just moves.) ## The bar for a docs PR -See [CONTRIBUTING.md](./CONTRIBUTING.md) — template used, placed coverage-aware, builds clean, technically accurate. +See [CONTRIBUTING.md](../CONTRIBUTING.md) — template used, placed coverage-aware, builds clean, technically accurate. ## Division of labor **Author** owns technical accuracy + a solid first draft. **Docs team** owns voice, structure, and placement. diff --git a/docs-enablement/enablement-walkthrough.md b/docs-enablement/enablement-walkthrough.md new file mode 100644 index 0000000000..e9af68db99 --- /dev/null +++ b/docs-enablement/enablement-walkthrough.md @@ -0,0 +1,85 @@ +# How a docs change would flow — a walkthrough to react to + +*A companion to the [pre-read](docs-team-preread.md). Nothing here is decided — it's a concrete "what would this actually feel like" so we're reacting to something real instead of a blank page. Mark it up.* + +The idea: **one flow, dialed to how much help a team needs** — from us drafting for a brand-new team, to a mature team self-serving with light review. Below is the flow followed all the way through for one change, then the same flow at three levels of support. + +**Tooling status legend:** ✅ **exists today** · 🟡 **drafted, staged on branch `docs-enablement`** (not merged) · ❌ **still to build**. Steps that depend on a ❌ item only fully hold once it ships — which is the whole reason for **tooling-first: the tools land before we ask SMEs to contribute.** + +--- + +## One change, start to finish + +**Scenario:** an engineer (the **contributor / SME**) ships a new user-facing setting → it needs a short task or concept page. A **writer** owns voice, structure, placement, and the merge. `main` is always publish-ready; **a merge to `main` fast-forwards to `latest`, so merge = live.** Work-in-progress and embargoed content stay on branches. + +### Part 1 — the contributor (SME) + +0. **Get access (one-time).** Requests write access; added as a **repo collaborator directly** — contributors work **in the repo, not a fork**. The clone already carries our conventions via the committed root `CLAUDE.md`. + - *Tooling:* ✅ repo write-access flow (already in use for cloud-docs contributors) · 🟡 committed root `CLAUDE.md` · ❌ `AGENTS.md` pointer for Codex users +1. **Track it.** Opens a "draft docs for <feature>" ticket (part of *their* definition of done), product-labeled, linked to the feature PR. For substantial work it pairs with a docs-team "review & publish" ticket. + - *Tooling:* ✅ Jira DOC project + `docs-rs`/`docs-k8s` labels + PR↔Jira autolink + Slack↔Jira sync · ❌ two-ticket automation +2. **Check what exists first.** Searches the docs; if a related page exists, **folds into / cross-links** it rather than making an orphan or duplicate. + - *Tooling:* ✅ repo grep + site search + Glean (cross-product) · ✅ `content/embeds/` (extend an embed vs. duplicate) · ❌ coverage-search step in `/draft-doc` +3. **Starts from a template.** `hugo new … --kind task`; sets `weight` to fit siblings, matches section `categories`. + - *Tooling:* ✅ Hugo `hugo new --kind` + generic default archetype · 🟡 per-type `archetypes/{task,concept,reference}.md` +4. **Drafts with AI in the repo.** Claude inherits `CLAUDE.md` → drafts in our voice. + - *Tooling:* ✅ Claude Code / Codex in-repo · ✅ per-product conventions (raw material) · 🟡 committed `CLAUDE.md` style rules · ❌ `/draft-doc` skill · ❌ author-voice profile +5. **Self-check + test.** Runs the self-review, fixes flags — then does the one thing tools can't: **actually runs the steps** and confirms it works. + - *Tooling:* ✅ Vale (local; starter kit built) · ✅ shortcode-path hook (local) · ✅ local `hugo` build · ✅ `/edit` · 🟡 `/docs:review-doc` · ❌ frontmatter validator +6. **Opens a PR.** Fills the docs checklist; adds an `aliases` entry for any moved content. Below the starting-place bar → we **bounce it back** with a pointer (it stays an edit, not a rewrite). + - *Tooling:* ✅ link-check + Hugo-build CI · ✅ `aliases` convention · 🟡 PR template + CONTRIBUTING + DoD · ❌ **PR-blocking gates** (link-check on `pull_request`, Vale-in-CI, shortcode hook → CI, frontmatter validator) — *the biggest gap: the gates aren't gates yet* + +### Part 2 — the writer + +0. **Ownership.** Primary (or backup) owner for the area, with a documented **team profile** (support tier, SMEs, conventions) so anyone can cover. + - *Tooling:* ✅ repo review rights · ❌ per-team profiles · ❌ primary+backup map +1. **Picks up the review.** A briefing over the review + bug queues surfaces the ticket + PR. + - *Tooling:* ✅ `/standup`·`/checkpoint`·`/pickup` suite (proven prototype) · ❌ team-adapted, queue-aware version +2. **Reviews at the right tier.** Routine additive → light lane (releases / security / API refs get the deep track). The human pass is **judgment-only** — voice, structure, placement, cross-links — because the gates handled the mechanics. Edits *from* the draft. + - *Tooling:* ✅ Andy's `.claude/commands/docs/*` (pattern to build on) · ❌ review-tier policy · ❌ review agent (structured-review comment) +3. **Readiness signal.** Until sign-off the page publishes as **"contributor-authored, pending docs-team review,"** upgraded to `reviewed` on approval — fast merge and honest signaling coexist. + - *Tooling:* ❌ `review_status` frontmatter field · ❌ page banner +4. **Merges → publishes.** Merges to `main`; protected paths require a human reviewer first; on merge `main` fast-forwards to `latest` → live, no manual publish step. + - *Tooling:* ✅ existing deploy pipeline · ✅ `main`+`latest` branches · ❌ CODEOWNERS · ❌ branch protection · ❌ `main → latest` auto-ff Action · ❌ gated auto-merge +5. **If something's wrong post-publish.** Publish is instant, so safety = **fast rollback**: a `revert` on `main` re-publishes the good state. + - *Tooling:* ✅ `git revert` (+ the auto-ff Action, once built) · ❌ rollback runbook step + +**Embargoed variant:** for a timed release, content sits on a **release branch** and merges to `main` at go-time, then auto-publishes. + +--- + +## Same flow, three levels of support + +The flow above is the **machinery**. What changes per team is only **how much of it we do vs. the SME**, the **entry-point bar**, and the **review depth** — never the quality bar or the gates. New teams start at ①; the default trajectory is *toward* ③. + +**① High-touch / hand-holding** — *new team, or complex / high-stakes content. This is the floor — the most support we offer.* +- **The dev reaches out** about a change that needs documenting **and provides source material** (accurate notes / a spec / a working config) — *not* a finished PR, but the initiation and the raw material are theirs. +- **We draft** from that material and own placement from the start; deep review; first few PRs reviewed regardless. +- **Manual merge**, "pending review" banner until sign-off. +- *Graduates once the team reliably supplies accurate, complete raw material.* +- ⚠️ **What this replaces:** some teams today expect **us to monitor the repo for changes and reach out to them** about what needs documenting — we carry the detection *and* the drafting. That's the piece that doesn't survive the new model: **the dev owns "there's a change → here's the material,"** not us. If change-detection happens at all, it's via **automated tooling** (a dev-repo scan surfacing PRs of docs interest), never a writer manually watching — and even then the dev still confirms and supplies the material. + +**② Light-touch** — *the walkthrough above; a team contributing steadily.* +- SME opens a **draft PR from a template**; we coach, review closely, own IA. +- We edit *from* their draft; **manual merge** after light review. +- *Graduates once their PRs clear the bar first-try with sound placement.* + +**③ Self-serve** — *goal state (e.g. a matured Iris).* +- Team **drafts + self-reviews + opens ready PRs**; we do a **light final review** only. +- **Gated auto-merge** (gates green + no Bugbot issues + self-review clean + a readiness label) — the Iris semi-automation ask, *earned*. Protected-path content still always gets a human. +- *Can move back to light-touch if quality slips (reviewed each quarter / per N PRs).* + +--- + +## What we'd need to build, in order + +1. 🔴 **Make the gates PR-blocking** — link-check on `pull_request`, Vale-in-CI, shortcode hook → CI, frontmatter validator. *(Everything else rests on this.)* +2. **Merge the staged contributor kit** — `CLAUDE.md` + per-type archetypes + CONTRIBUTING + PR template + DoD. +3. `/docs:review-doc` self-review skill. +4. CODEOWNERS + branch protection (the protected-path floor). +5. `main → latest` auto-ff Action (merge = live). +6. `review_status` field + page banner. +7. `/draft-doc` + the review agent. +8. Two-ticket automation, per-team profiles, team-adapted `/standup`. + +**The one honest caveat:** every ❌ above is why we can't ask teams to contribute yet — this is the picture *after* the tools ship. That ordering (tools first) is the thing I most want us to agree on Wednesday. From 6eb0166b0c88082eddb7f49e55a576e255770425 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Mon, 27 Jul 2026 12:00:02 -0500 Subject: [PATCH 4/8] review feedback edits --- CONTRIBUTING.md | 1 + docs-enablement/docs-definition-of-done.md | 1 + docs-enablement/enablement-walkthrough.md | 26 ++++++++++------------ 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ba42e92a4..215ef1ee86 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,6 +7,7 @@ Thanks for helping keep our docs accurate and useful. Docs are part of a feature ## Do I need to write docs for this change? - **No user-facing change** (refactor, internal, tests, CI) → **no docs.** Note "no docs needed" on your PR. +- **New product or feature area** → **yes** — start with the docs team on where it lives before writing. - **New feature, behavior, or setting** → **yes** — a short task or concept page. - **New or changed API / config field** → **update the reference** (often auto-generated — check with the docs team first). diff --git a/docs-enablement/docs-definition-of-done.md b/docs-enablement/docs-definition-of-done.md index a30c435a3b..e077d2ded4 100644 --- a/docs-enablement/docs-definition-of-done.md +++ b/docs-enablement/docs-definition-of-done.md @@ -7,6 +7,7 @@ A change is **docs-done** when the matching row is satisfied: | Change type | What's required | |---|---| | No user-facing impact (refactor, internal, tests, CI) | Assert **"no docs needed"** on the PR. | +| New **product or major feature area** | A net-new docs section — **coordinate with the docs team on structure and placement first**, then contribute pages from the templates. | | New or changed user-facing **feature, behavior, setting, or default** | A **docs PR** — a task or concept page from the template, meeting the contribution bar, **tested (steps/commands actually run)**. | | New or changed **API, CRD, or config field** | The relevant **reference updated** (often auto-generated — coordinate with docs). | | **Deprecation or removal** | A **release-note entry** + affected pages updated. | diff --git a/docs-enablement/enablement-walkthrough.md b/docs-enablement/enablement-walkthrough.md index e9af68db99..6bdb397041 100644 --- a/docs-enablement/enablement-walkthrough.md +++ b/docs-enablement/enablement-walkthrough.md @@ -10,12 +10,12 @@ The idea: **one flow, dialed to how much help a team needs** — from us draftin ## One change, start to finish -**Scenario:** an engineer (the **contributor / SME**) ships a new user-facing setting → it needs a short task or concept page. A **writer** owns voice, structure, placement, and the merge. `main` is always publish-ready; **a merge to `main` fast-forwards to `latest`, so merge = live.** Work-in-progress and embargoed content stay on branches. +**Scenario:** an engineer (the **contributor / SME**) is developing a new user-facing setting → it needs a short task or concept page. A **writer** owns voice, structure, placement, and the merge. `main` is always publish-ready; **a merge to `main` fast-forwards to `latest`, so merge = live.** Work-in-progress and embargoed content stay on branches. ### Part 1 — the contributor (SME) -0. **Get access (one-time).** Requests write access; added as a **repo collaborator directly** — contributors work **in the repo, not a fork**. The clone already carries our conventions via the committed root `CLAUDE.md`. - - *Tooling:* ✅ repo write-access flow (already in use for cloud-docs contributors) · 🟡 committed root `CLAUDE.md` · ❌ `AGENTS.md` pointer for Codex users +0. **Get access.** Fork the repo and open PRs from your fork — that works out of the box. Prefer to work directly in the repo instead? Ask in **#ask-docs** and we'll add you as a collaborator. Either way the clone carries our conventions via the committed root `CLAUDE.md`. + - *Tooling:* ✅ fork + PR flow (works today) · ✅ repo write-access flow (already in use for cloud-docs contributors) · 🟡 committed root `CLAUDE.md` · ❌ `AGENTS.md` pointer for Codex users 1. **Track it.** Opens a "draft docs for <feature>" ticket (part of *their* definition of done), product-labeled, linked to the feature PR. For substantial work it pairs with a docs-team "review & publish" ticket. - *Tooling:* ✅ Jira DOC project + `docs-rs`/`docs-k8s` labels + PR↔Jira autolink + Slack↔Jira sync · ❌ two-ticket automation 2. **Check what exists first.** Searches the docs; if a related page exists, **folds into / cross-links** it rather than making an orphan or duplicate. @@ -37,11 +37,9 @@ The idea: **one flow, dialed to how much help a team needs** — from us draftin - *Tooling:* ✅ `/standup`·`/checkpoint`·`/pickup` suite (proven prototype) · ❌ team-adapted, queue-aware version 2. **Reviews at the right tier.** Routine additive → light lane (releases / security / API refs get the deep track). The human pass is **judgment-only** — voice, structure, placement, cross-links — because the gates handled the mechanics. Edits *from* the draft. - *Tooling:* ✅ Andy's `.claude/commands/docs/*` (pattern to build on) · ❌ review-tier policy · ❌ review agent (structured-review comment) -3. **Readiness signal.** Until sign-off the page publishes as **"contributor-authored, pending docs-team review,"** upgraded to `reviewed` on approval — fast merge and honest signaling coexist. - - *Tooling:* ❌ `review_status` frontmatter field · ❌ page banner -4. **Merges → publishes.** Merges to `main`; protected paths require a human reviewer first; on merge `main` fast-forwards to `latest` → live, no manual publish step. +3. **Merges → publishes.** Merges to `main`; protected paths require a human reviewer first; on merge `main` fast-forwards to `latest` → live, no manual publish step. - *Tooling:* ✅ existing deploy pipeline · ✅ `main`+`latest` branches · ❌ CODEOWNERS · ❌ branch protection · ❌ `main → latest` auto-ff Action · ❌ gated auto-merge -5. **If something's wrong post-publish.** Publish is instant, so safety = **fast rollback**: a `revert` on `main` re-publishes the good state. +4. **If something's wrong post-publish.** Publish is instant, so safety = **fast rollback**: a `revert` on `main` re-publishes the good state. - *Tooling:* ✅ `git revert` (+ the auto-ff Action, once built) · ❌ rollback runbook step **Embargoed variant:** for a timed release, content sits on a **release branch** and merges to `main` at go-time, then auto-publishes. @@ -50,14 +48,14 @@ The idea: **one flow, dialed to how much help a team needs** — from us draftin ## Same flow, three levels of support -The flow above is the **machinery**. What changes per team is only **how much of it we do vs. the SME**, the **entry-point bar**, and the **review depth** — never the quality bar or the gates. New teams start at ①; the default trajectory is *toward* ③. +The flow above is the **machinery**, and the whole point of it is that documenting a change gets **faster and simpler for everyone** — not that the work just moves onto the SME. What changes per team is only **how much we do together vs. the SME alone**, the **entry-point bar**, and the **review depth** — never the quality bar or the gates. New teams start at ①; the default trajectory is *toward* ③. **① High-touch / hand-holding** — *new team, or complex / high-stakes content. This is the floor — the most support we offer.* -- **The dev reaches out** about a change that needs documenting **and provides source material** (accurate notes / a spec / a working config) — *not* a finished PR, but the initiation and the raw material are theirs. -- **We draft** from that material and own placement from the start; deep review; first few PRs reviewed regardless. -- **Manual merge**, "pending review" banner until sign-off. +- **We gather the material and use automated change-detection** — a dev-repo scan surfaces docs-relevant PRs so changes don't slip, and we pull together the notes / spec / working config with the dev and draft from there. +- **We draft** and own placement from the start; deep review; first few PRs reviewed regardless. +- **Manual merge** after sign-off. - *Graduates once the team reliably supplies accurate, complete raw material.* -- ⚠️ **What this replaces:** some teams today expect **us to monitor the repo for changes and reach out to them** about what needs documenting — we carry the detection *and* the drafting. That's the piece that doesn't survive the new model: **the dev owns "there's a change → here's the material,"** not us. If change-detection happens at all, it's via **automated tooling** (a dev-repo scan surfacing PRs of docs interest), never a writer manually watching — and even then the dev still confirms and supplies the material. +- ⚠️ **What this replaces:** the old status quo where **a writer manually watches the repo** for changes. Detection is now **automated** (the dev-repo scan), and the dev still confirms and supplies the material — the piece that goes away is the writer monitoring by hand. **② Light-touch** — *the walkthrough above; a team contributing steadily.* - SME opens a **draft PR from a template**; we coach, review closely, own IA. @@ -66,14 +64,14 @@ The flow above is the **machinery**. What changes per team is only **how much of **③ Self-serve** — *goal state (e.g. a matured Iris).* - Team **drafts + self-reviews + opens ready PRs**; we do a **light final review** only. -- **Gated auto-merge** (gates green + no Bugbot issues + self-review clean + a readiness label) — the Iris semi-automation ask, *earned*. Protected-path content still always gets a human. +- **Gated auto-merge** for routine content (gates green + no Bugbot issues + self-review clean + a readiness label) — the Iris semi-automation ask, *earned*. **Security-relevant changes always get a human reviewer before publish, on every path** — no auto-merge exceptions. - *Can move back to light-touch if quality slips (reviewed each quarter / per N PRs).* --- ## What we'd need to build, in order -1. 🔴 **Make the gates PR-blocking** — link-check on `pull_request`, Vale-in-CI, shortcode hook → CI, frontmatter validator. *(Everything else rests on this.)* +1. 🔴 **Add the PR gates, tiered by strictness.** **Blocking:** valid frontmatter + Hugo build + shortcode paths — a broken build is a broken live page, so these stop a merge. **Advisory (non-blocking):** link-check and Vale style — surfaced on the PR to fix, never a merge-blocker. *(Everything else rests on this.)* 2. **Merge the staged contributor kit** — `CLAUDE.md` + per-type archetypes + CONTRIBUTING + PR template + DoD. 3. `/docs:review-doc` self-review skill. 4. CODEOWNERS + branch protection (the protected-path floor). From 5c1a9b77b7d052ea5b018a01af7d5cf102e9a024 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Mon, 27 Jul 2026 12:08:26 -0500 Subject: [PATCH 5/8] changes to aim at contributors --- CONTRIBUTING.md | 2 +- docs-enablement/docs-definition-of-done.md | 6 +- docs-enablement/enablement-walkthrough.md | 83 ---------------------- 3 files changed, 3 insertions(+), 88 deletions(-) delete mode 100644 docs-enablement/enablement-walkthrough.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 215ef1ee86..3619e373f6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ Full policy: [Definition of Done: Docs](./docs-enablement/docs-definition-of-don 2. **Copy the template** for your doc type from `archetypes/` (`task` / `concept` / `reference`), or run `hugo new content//.md --kind task`. 3. **Draft with AI in the repo.** Claude inherits our style from the committed `CLAUDE.md` — give it your notes and ask it to draft in our conventions. 4. **Self-check.** Run `/docs:review-doc` (or at least Vale + the link check + a local `hugo` build) and fix what it flags. -5. **Open a PR** and fill the docs checklist. A docs teammate reviews for voice and structure, then merges. +5. **Open a PR** and fill the docs checklist. A docs teammate reviews for voice, structure, and placement, then merges. Merging to `main` publishes to the live site automatically — so review happens *before* merge, and changes to sensitive areas (security, release notes) always get a human reviewer first. ## Templates diff --git a/docs-enablement/docs-definition-of-done.md b/docs-enablement/docs-definition-of-done.md index e077d2ded4..7de16a318f 100644 --- a/docs-enablement/docs-definition-of-done.md +++ b/docs-enablement/docs-definition-of-done.md @@ -23,7 +23,5 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md) — template used, placed coverage-awa ## Division of labor **Author** owns technical accuracy + a solid first draft. **Docs team** owns voice, structure, and placement. -## Open for leadership / eng leads -- Ratify this definition and **re-broadcast it with these specifics** (the original message lacked them). -- Agree **where the tripwire lives**: PR-template checkbox (light) vs. a merge gate (strict). -- Confirm the change-type rows match how teams actually ship. +## A note on enforcement +The exact enforcement mechanism (a self-attested PR checkbox versus a required merge gate) is still being finalized with engineering leadership. For now, treat the table above as the working definition — and if a row doesn't match how your team actually ships, flag it in **#ask-docs** so we can adjust it. diff --git a/docs-enablement/enablement-walkthrough.md b/docs-enablement/enablement-walkthrough.md deleted file mode 100644 index 6bdb397041..0000000000 --- a/docs-enablement/enablement-walkthrough.md +++ /dev/null @@ -1,83 +0,0 @@ -# How a docs change would flow — a walkthrough to react to - -*A companion to the [pre-read](docs-team-preread.md). Nothing here is decided — it's a concrete "what would this actually feel like" so we're reacting to something real instead of a blank page. Mark it up.* - -The idea: **one flow, dialed to how much help a team needs** — from us drafting for a brand-new team, to a mature team self-serving with light review. Below is the flow followed all the way through for one change, then the same flow at three levels of support. - -**Tooling status legend:** ✅ **exists today** · 🟡 **drafted, staged on branch `docs-enablement`** (not merged) · ❌ **still to build**. Steps that depend on a ❌ item only fully hold once it ships — which is the whole reason for **tooling-first: the tools land before we ask SMEs to contribute.** - ---- - -## One change, start to finish - -**Scenario:** an engineer (the **contributor / SME**) is developing a new user-facing setting → it needs a short task or concept page. A **writer** owns voice, structure, placement, and the merge. `main` is always publish-ready; **a merge to `main` fast-forwards to `latest`, so merge = live.** Work-in-progress and embargoed content stay on branches. - -### Part 1 — the contributor (SME) - -0. **Get access.** Fork the repo and open PRs from your fork — that works out of the box. Prefer to work directly in the repo instead? Ask in **#ask-docs** and we'll add you as a collaborator. Either way the clone carries our conventions via the committed root `CLAUDE.md`. - - *Tooling:* ✅ fork + PR flow (works today) · ✅ repo write-access flow (already in use for cloud-docs contributors) · 🟡 committed root `CLAUDE.md` · ❌ `AGENTS.md` pointer for Codex users -1. **Track it.** Opens a "draft docs for <feature>" ticket (part of *their* definition of done), product-labeled, linked to the feature PR. For substantial work it pairs with a docs-team "review & publish" ticket. - - *Tooling:* ✅ Jira DOC project + `docs-rs`/`docs-k8s` labels + PR↔Jira autolink + Slack↔Jira sync · ❌ two-ticket automation -2. **Check what exists first.** Searches the docs; if a related page exists, **folds into / cross-links** it rather than making an orphan or duplicate. - - *Tooling:* ✅ repo grep + site search + Glean (cross-product) · ✅ `content/embeds/` (extend an embed vs. duplicate) · ❌ coverage-search step in `/draft-doc` -3. **Starts from a template.** `hugo new … --kind task`; sets `weight` to fit siblings, matches section `categories`. - - *Tooling:* ✅ Hugo `hugo new --kind` + generic default archetype · 🟡 per-type `archetypes/{task,concept,reference}.md` -4. **Drafts with AI in the repo.** Claude inherits `CLAUDE.md` → drafts in our voice. - - *Tooling:* ✅ Claude Code / Codex in-repo · ✅ per-product conventions (raw material) · 🟡 committed `CLAUDE.md` style rules · ❌ `/draft-doc` skill · ❌ author-voice profile -5. **Self-check + test.** Runs the self-review, fixes flags — then does the one thing tools can't: **actually runs the steps** and confirms it works. - - *Tooling:* ✅ Vale (local; starter kit built) · ✅ shortcode-path hook (local) · ✅ local `hugo` build · ✅ `/edit` · 🟡 `/docs:review-doc` · ❌ frontmatter validator -6. **Opens a PR.** Fills the docs checklist; adds an `aliases` entry for any moved content. Below the starting-place bar → we **bounce it back** with a pointer (it stays an edit, not a rewrite). - - *Tooling:* ✅ link-check + Hugo-build CI · ✅ `aliases` convention · 🟡 PR template + CONTRIBUTING + DoD · ❌ **PR-blocking gates** (link-check on `pull_request`, Vale-in-CI, shortcode hook → CI, frontmatter validator) — *the biggest gap: the gates aren't gates yet* - -### Part 2 — the writer - -0. **Ownership.** Primary (or backup) owner for the area, with a documented **team profile** (support tier, SMEs, conventions) so anyone can cover. - - *Tooling:* ✅ repo review rights · ❌ per-team profiles · ❌ primary+backup map -1. **Picks up the review.** A briefing over the review + bug queues surfaces the ticket + PR. - - *Tooling:* ✅ `/standup`·`/checkpoint`·`/pickup` suite (proven prototype) · ❌ team-adapted, queue-aware version -2. **Reviews at the right tier.** Routine additive → light lane (releases / security / API refs get the deep track). The human pass is **judgment-only** — voice, structure, placement, cross-links — because the gates handled the mechanics. Edits *from* the draft. - - *Tooling:* ✅ Andy's `.claude/commands/docs/*` (pattern to build on) · ❌ review-tier policy · ❌ review agent (structured-review comment) -3. **Merges → publishes.** Merges to `main`; protected paths require a human reviewer first; on merge `main` fast-forwards to `latest` → live, no manual publish step. - - *Tooling:* ✅ existing deploy pipeline · ✅ `main`+`latest` branches · ❌ CODEOWNERS · ❌ branch protection · ❌ `main → latest` auto-ff Action · ❌ gated auto-merge -4. **If something's wrong post-publish.** Publish is instant, so safety = **fast rollback**: a `revert` on `main` re-publishes the good state. - - *Tooling:* ✅ `git revert` (+ the auto-ff Action, once built) · ❌ rollback runbook step - -**Embargoed variant:** for a timed release, content sits on a **release branch** and merges to `main` at go-time, then auto-publishes. - ---- - -## Same flow, three levels of support - -The flow above is the **machinery**, and the whole point of it is that documenting a change gets **faster and simpler for everyone** — not that the work just moves onto the SME. What changes per team is only **how much we do together vs. the SME alone**, the **entry-point bar**, and the **review depth** — never the quality bar or the gates. New teams start at ①; the default trajectory is *toward* ③. - -**① High-touch / hand-holding** — *new team, or complex / high-stakes content. This is the floor — the most support we offer.* -- **We gather the material and use automated change-detection** — a dev-repo scan surfaces docs-relevant PRs so changes don't slip, and we pull together the notes / spec / working config with the dev and draft from there. -- **We draft** and own placement from the start; deep review; first few PRs reviewed regardless. -- **Manual merge** after sign-off. -- *Graduates once the team reliably supplies accurate, complete raw material.* -- ⚠️ **What this replaces:** the old status quo where **a writer manually watches the repo** for changes. Detection is now **automated** (the dev-repo scan), and the dev still confirms and supplies the material — the piece that goes away is the writer monitoring by hand. - -**② Light-touch** — *the walkthrough above; a team contributing steadily.* -- SME opens a **draft PR from a template**; we coach, review closely, own IA. -- We edit *from* their draft; **manual merge** after light review. -- *Graduates once their PRs clear the bar first-try with sound placement.* - -**③ Self-serve** — *goal state (e.g. a matured Iris).* -- Team **drafts + self-reviews + opens ready PRs**; we do a **light final review** only. -- **Gated auto-merge** for routine content (gates green + no Bugbot issues + self-review clean + a readiness label) — the Iris semi-automation ask, *earned*. **Security-relevant changes always get a human reviewer before publish, on every path** — no auto-merge exceptions. -- *Can move back to light-touch if quality slips (reviewed each quarter / per N PRs).* - ---- - -## What we'd need to build, in order - -1. 🔴 **Add the PR gates, tiered by strictness.** **Blocking:** valid frontmatter + Hugo build + shortcode paths — a broken build is a broken live page, so these stop a merge. **Advisory (non-blocking):** link-check and Vale style — surfaced on the PR to fix, never a merge-blocker. *(Everything else rests on this.)* -2. **Merge the staged contributor kit** — `CLAUDE.md` + per-type archetypes + CONTRIBUTING + PR template + DoD. -3. `/docs:review-doc` self-review skill. -4. CODEOWNERS + branch protection (the protected-path floor). -5. `main → latest` auto-ff Action (merge = live). -6. `review_status` field + page banner. -7. `/draft-doc` + the review agent. -8. Two-ticket automation, per-team profiles, team-adapted `/standup`. - -**The one honest caveat:** every ❌ above is why we can't ask teams to contribute yet — this is the picture *after* the tools ship. That ordering (tools first) is the thing I most want us to agree on Wednesday. From 54932192078a983525b184b23f93c63ea8128d0e Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Mon, 27 Jul 2026 12:47:48 -0500 Subject: [PATCH 6/8] correct doc channel --- CONTRIBUTING.md | 4 ++-- docs-enablement/docs-definition-of-done.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3619e373f6..398a3416c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,7 +11,7 @@ Thanks for helping keep our docs accurate and useful. Docs are part of a feature - **New feature, behavior, or setting** → **yes** — a short task or concept page. - **New or changed API / config field** → **update the reference** (often auto-generated — check with the docs team first). -Full policy: [Definition of Done: Docs](./docs-enablement/docs-definition-of-done.md). When unsure, ask in **#ask-docs** — a 30-second question beats a missed page. +Full policy: [Definition of Done: Docs](./docs-enablement/docs-definition-of-done.md). When unsure, ask in **#docs** — a 30-second question beats a missed page. ## The golden path @@ -46,4 +46,4 @@ If it's missing these, we'll send it back with a pointer — not to be difficult ## Getting help -Ask in **#ask-docs**, or tag a docs teammate on your PR. +Ask in **#docs**, or tag a docs teammate on your PR. diff --git a/docs-enablement/docs-definition-of-done.md b/docs-enablement/docs-definition-of-done.md index 7de16a318f..2780f129e7 100644 --- a/docs-enablement/docs-definition-of-done.md +++ b/docs-enablement/docs-definition-of-done.md @@ -24,4 +24,4 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md) — template used, placed coverage-awa **Author** owns technical accuracy + a solid first draft. **Docs team** owns voice, structure, and placement. ## A note on enforcement -The exact enforcement mechanism (a self-attested PR checkbox versus a required merge gate) is still being finalized with engineering leadership. For now, treat the table above as the working definition — and if a row doesn't match how your team actually ships, flag it in **#ask-docs** so we can adjust it. +The exact enforcement mechanism (a self-attested PR checkbox versus a required merge gate) is still being finalized with engineering leadership. For now, treat the table above as the working definition — and if a row doesn't match how your team actually ships, flag it in **#docs** so we can adjust it. From 0527a39e860aa5245e083742264e427a8fec7849 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Mon, 27 Jul 2026 13:37:26 -0500 Subject: [PATCH 7/8] add concrete steps --- CONTRIBUTING.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 398a3416c1..7f5e0a96c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,20 +15,24 @@ Full policy: [Definition of Done: Docs](./docs-enablement/docs-definition-of-don ## The golden path -1. **Check what exists.** Search the docs for your topic; if there's a related page, add to it instead of creating a new one. -2. **Copy the template** for your doc type from `archetypes/` (`task` / `concept` / `reference`), or run `hugo new content//.md --kind task`. -3. **Draft with AI in the repo.** Claude inherits our style from the committed `CLAUDE.md` — give it your notes and ask it to draft in our conventions. -4. **Self-check.** Run `/docs:review-doc` (or at least Vale + the link check + a local `hugo` build) and fix what it flags. -5. **Open a PR** and fill the docs checklist. A docs teammate reviews for voice, structure, and placement, then merges. Merging to `main` publishes to the live site automatically — so review happens *before* merge, and changes to sensitive areas (security, release notes) always get a human reviewer first. +Each step names the actual action — a prompt to the AI, a command, or a click. + +1. **Check what already exists.** Ask Claude or Codex in the repo: *"Is there already a page about `` under `content/`? If so, where, and should I add to it instead of making a new one?"* — or in the editor, `Cmd/Ctrl+Shift+F` across `content/` for the topic, and check the search box on the docs site. If there's a related page, add to it instead of creating a new one. +2. **Create a branch and stamp out the template.** From an up-to-date `main`, `git checkout -b DOC-xxxx` (or ask the AI to). Then generate the page from the right archetype: `hugo new content//.md --kind task` (or `concept` / `reference`) — that drops in the template with frontmatter and section scaffolding. Open the new file. +3. **Draft with AI in the repo.** In the Claude Code (or Codex) panel, paste your source material and ask it to draft — *"Draft this task page from these notes: ``."* It reads the committed `CLAUDE.md` automatically, so the draft comes out in our voice, naming, and shortcodes. +4. **Self-check and preview.** Run `/docs:review-doc` — or manually: `vale content/`, the link check, and `make serve`, then open `http://localhost:1313` to eyeball the page. Fix what's flagged, then actually run the steps or commands the page describes to confirm they work. +5. **Open a PR.** Commit and push the branch (or tell the AI "commit and push this branch"), then open a PR on GitHub — the PR template auto-loads the docs checklist, so fill it in and request a reviewer. A docs teammate reviews for voice, structure, and placement, then merges. Merging to `main` publishes to the live site automatically — so review happens *before* merge, and changes to sensitive areas (security, release notes) always get a human reviewer first. ## Templates -Per-type starting points live in **`archetypes/`**: `task` (how-to), `concept` (what/why), `reference` (fields/options). Each has inline guidance — delete the comments before publishing. +Per-type starting points live in **`archetypes/`**: `task` (how-to), `concept` (what/why), `reference` (fields/options). To use one, run `hugo new content//.md --kind task` (or `concept` / `reference`), or copy the archetype file into place. Each has inline guidance — delete the comments before publishing. ## Style We follow Google developer style. The full rules live in the committed **`CLAUDE.md`**, so AI drafting in the repo inherits them automatically. The short version: write to "you," active voice, present tense; sentence-case headings; verb-first task titles; angle-bracket `` in code; descriptive link text; no marketing language. +To check a draft against the style, run `/docs:review-doc`, or ask the AI: *"Check this page against our style rules in `CLAUDE.md` and flag anything off."* + ## What makes a PR ready for review (the bar) A docs teammate edits *from* your draft — they can't rewrite it from scratch. Before you request review, make sure it: @@ -38,6 +42,8 @@ A docs teammate edits *from* your draft — they can't rewrite it from scratch. - [ ] **Builds clean**, with complete frontmatter (CI will tell you) - [ ] Is **technically accurate — and you've tested it** (followed the steps / ran the commands / checked the output), not just written it — the part only you can guarantee +Run `/docs:review-doc` before you open the PR — it checks most of these at once (template, placement, build, frontmatter). The last one, testing it, is the part only you can do. + If it's missing these, we'll send it back with a pointer — not to be difficult, but because that bar is what lets a small docs team keep up. ## Who owns what From 657b103dfe7de7fe780b9c38154432e024a8cd2e Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Mon, 27 Jul 2026 13:39:38 -0500 Subject: [PATCH 8/8] remove dod page --- CONTRIBUTING.md | 2 +- docs-enablement/docs-definition-of-done.md | 27 ---------------------- 2 files changed, 1 insertion(+), 28 deletions(-) delete mode 100644 docs-enablement/docs-definition-of-done.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7f5e0a96c1..bcdfe6c4f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,7 +11,7 @@ Thanks for helping keep our docs accurate and useful. Docs are part of a feature - **New feature, behavior, or setting** → **yes** — a short task or concept page. - **New or changed API / config field** → **update the reference** (often auto-generated — check with the docs team first). -Full policy: [Definition of Done: Docs](./docs-enablement/docs-definition-of-done.md). When unsure, ask in **#docs** — a 30-second question beats a missed page. +When unsure, ask in **#docs** — a 30-second question beats a missed page. ## The golden path diff --git a/docs-enablement/docs-definition-of-done.md b/docs-enablement/docs-definition-of-done.md deleted file mode 100644 index 2780f129e7..0000000000 --- a/docs-enablement/docs-definition-of-done.md +++ /dev/null @@ -1,27 +0,0 @@ -# Definition of Done: Docs - -"Docs are part of the definition of done" — here's what that concretely means, scaled to the size of the change so it's realistic. - -A change is **docs-done** when the matching row is satisfied: - -| Change type | What's required | -|---|---| -| No user-facing impact (refactor, internal, tests, CI) | Assert **"no docs needed"** on the PR. | -| New **product or major feature area** | A net-new docs section — **coordinate with the docs team on structure and placement first**, then contribute pages from the templates. | -| New or changed user-facing **feature, behavior, setting, or default** | A **docs PR** — a task or concept page from the template, meeting the contribution bar, **tested (steps/commands actually run)**. | -| New or changed **API, CRD, or config field** | The relevant **reference updated** (often auto-generated — coordinate with docs). | -| **Deprecation or removal** | A **release-note entry** + affected pages updated. | - -## How it's enforced (engineering-owned, not docs-policed) -- **PR template** docs checklist — self-attested by the author. -- **Eng lead** confirms at PR review / sprint close. -- **Docs team provides** the templates, style, tooling, and final review — *not* enforcement. (If docs chases every PR, the bottleneck just moves.) - -## The bar for a docs PR -See [CONTRIBUTING.md](../CONTRIBUTING.md) — template used, placed coverage-aware, builds clean, technically accurate. - -## Division of labor -**Author** owns technical accuracy + a solid first draft. **Docs team** owns voice, structure, and placement. - -## A note on enforcement -The exact enforcement mechanism (a self-attested PR checkbox versus a required merge gate) is still being finalized with engineering leadership. For now, treat the table above as the working definition — and if a row doesn't match how your team actually ships, flag it in **#docs** so we can adjust it.