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/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 new file mode 100644 index 0000000000..c1a5e80300 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,57 @@ +# 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. 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. + +## 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..bcdfe6c4f2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# 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 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). + +When unsure, ask in **#docs** — a 30-second question beats a missed page. + +## The golden path + +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). 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: + +- [ ] 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 + +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 + +**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**, 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/..." >}})