Infra: docs enablement first attempt by kaitlynmichael · Pull Request #3689 · redis/docs

kaitlynmichael · 2026-07-21T23:17:20Z

Note

Low Risk
Process and template-only changes with no runtime or published user doc content; risk is limited to contributor guidance and PR expectations, not production behavior.

Overview
Introduces docs contributor infrastructure so humans and AI tools share one style bar and a repeatable workflow before PR review.

CLAUDE.md codifies Redis docs writing rules (Google dev style, voice, terminology, frontmatter, coverage-first IA, placeholders/security). AGENTS.md tells Codex and other agents to follow the same file. CONTRIBUTING.md documents when docs are required, the golden path (search → hugo new archetype → AI draft → self-check → PR), templates, and the “ready for review” bar.

Adds a GitHub PR template with a docs checklist (coverage, template type, build/frontmatter, accuracy, style) plus a “no docs needed” escape hatch for non–user-facing changes.

Adds Hugo archetypes/ for task, concept, and reference pages with frontmatter scaffolding and inline author guidance.

Adds a first-cut Claude command spec .claude/commands/docs/review-doc describing deterministic checks (Vale, links, Hugo build, frontmatter) and an AI rubric (voice, structure, IA, security placeholders); implementation mechanics are explicitly left as a stub/TODO.

^{Reviewed by Cursor Bugbot for commit 657b103. Bugbot is set up for automated code reviews on this repo. Configure here.}

mich-elle-luna

thank you! Just a few thoughts off the top of my head

mich-elle-luna · 2026-07-22T22:34:37Z

@@ -0,0 +1,5 @@
+# AGENTS.md


I think AGENTS.md is a special name that is used for something else

AGENTS.md is actually the intended name here — it's the emerging cross-tool open standard for agent instructions (Codex, Cursor, and others auto-read a root AGENTS.md). Since a lot of the company uses Cursor or Codex, I think it's necessary: it routes those tools to the same rules in CLAUDE.md, so there's still a single source of truth for style and conventions. So it's not colliding with anything — it is the special name, pointed at our one source.

mich-elle-luna · 2026-07-22T22:43:10Z

+
+| Change type | What's required |
+|---|---|
+| No user-facing impact (refactor, internal, tests, CI) | Assert **"no docs needed"** on the PR. |


We should add new product

mich-elle-luna · 2026-07-22T23:15:16Z

+
+## 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.


add new product

github-actions · 2026-07-27T17:10:01Z

🧠 Redis Memory

Found 5 related items from repository history:

PR — FF: restructure and edit
PR — DOC-6154 Augment-friendly features in the repo for doc tasks

For a little while now, we've had some Markdown files that contain docs to help AI to perform particular tasks (eg, how to modify the code e
PR — Doc home update

Here is a new draft of the docs home page in response to feedback that the current one is overwhelming and to help make the main options mor
PR — Update workflow to be able to handle new doc structure
PR — DOC-6809 Docs-only MCP server: spec + v0 prototype

Note: not finished - just using the PR for Bugbot feedback so far.

Memory updated at 5c1a9b7

github-actions · 2026-07-27T17:48:12Z

🧠 Redis Memory

Found 5 related items from repository history:

PR — DOC-6154 Augment-friendly features in the repo for doc tasks

For a little while now, we've had some Markdown files that contain docs to help AI to perform particular tasks (eg, how to modify the code e
PR — Doc home update

Here is a new draft of the docs home page in response to feedback that the current one is overwhelming and to help make the main options mor
PR — DOC-6809 Docs-only MCP server: spec + v0 prototype

Note: not finished - just using the PR for Bugbot feedback so far.
PR — Add styled landing page intros to AI and context engine docs

Adds tagline, three clickable cards, "What is X?" and "Why use X?" sections with Redis-palette styling to the Redis for AI, Context Engine,
PR — FF: restructure and edit

Memory updated at 5493219

github-actions · 2026-07-27T18:40:02Z

🧠 Redis Memory

Found 5 related items from repository history:

PR — DOC-6154 Augment-friendly features in the repo for doc tasks

For a little while now, we've had some Markdown files that contain docs to help AI to perform particular tasks (eg, how to modify the code e
PR — Doc home update

Here is a new draft of the docs home page in response to feedback that the current one is overwhelming and to help make the main options mor
PR — FF: restructure and edit
PR — Update workflow to be able to handle new doc structure
PR — DOC-6809 Docs-only MCP server: spec + v0 prototype

Note: not finished - just using the PR for Bugbot feedback so far.

Memory updated at 657b103

andy-stark-redis

Just a few thoughts and suggestions - it's looking pretty good so far :-)

andy-stark-redis · 2026-07-28T14:42:41Z

@@ -0,0 +1,36 @@
+---


Page templates might be a good idea to have. However, I'm not sure if the ones you've got here make it look like these are strict heading structures that we already use (not every reference page needs a syntax section, for example). Also, maybe we should consider using mdschema for this? It can create page boilerplate like this but can also validate the structure (eg, it can check that required frontmatter fields are present and of the right type, like an integer for the weight, etc).

andy-stark-redis · 2026-07-28T14:49:17Z

@@ -0,0 +1,16 @@
+## Summary


An AI tool won't see these directly, but if a human sees this, will they really know if the checks have been passed or not (it will probably be AI that writes the page)? We might want something like /make-pr skill that actually opens the PR; the skill could contain a checklist like this that the AI could use.

andy-stark-redis · 2026-07-28T14:52:47Z

@@ -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.


Maybe link to these explicitly?

Suggested change

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.

Base style: [**Google developer documentation style**](https://developers.google.com/style); fall back to the [**Microsoft Writing Style Guide**](https://learn.microsoft.com/en-us/style-guide/welcome/) where Google is silent. Follow these on every docs change. AI tools working in this repo inherit these rules automatically.

andy-stark-redis · 2026-07-28T15:05:19Z

@@ -0,0 +1,36 @@
+---


It might be worth making this into a skill rather than a command. The reason is that a command has to be invoked explicitly with the slash syntax, whereas the LLM can use a skill at its own discretion when the task seems to require it. If we use a command then we should explicitly say somewhere "Type /docs:review-doc to run the review". Otherwise, people might say "please review what I've just written", etc, and the LLM won't run the command.

andy-stark-redis · 2026-07-28T15:13:01Z

+## 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.


The LLM might not know about _index.md pages with auto-indexing (ie, hideListLinks not set to true). Maybe we should start using hideListLinks: false and add links in the content for all section index pages? The auto-generated lists don't look very good anyway.

andy-stark-redis · 2026-07-28T15:22:58Z

+
+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 `<topic>` 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.


Maybe mention that a well-written Jira ticket or a discussion on a Slack thread is often a good starting point for a docs plan? Claude can access both from VSCode using the connectors. Claude Tag or the Jira tool can make a Jira ticket by summarising a Slack thread.

andy-stark-redis · 2026-07-28T15:25:14Z

+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: `<spec>`."* 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/<path>`, 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.
+


Maybe mention that they should expect Bugbot feedback sometimes, but they can handle it easily using /docs:bugbot.

kaitlynmichael · 2026-07-28T17:12:34Z

Closing in favor of using one file (onboarding.md) which Michelle is developing.

kaitlynmichael added 3 commits July 21, 2026 11:09

docs enablement first attempt

045b138

add agents file

55554bb

walkthrough

6712f02

kaitlynmichael self-assigned this Jul 21, 2026

kaitlynmichael added the test - do not merge label Jul 21, 2026

mich-elle-luna reviewed Jul 22, 2026

View reviewed changes

kaitlynmichael marked this pull request as ready for review July 27, 2026 15:32

kaitlynmichael added 4 commits July 27, 2026 10:38

Merge remote-tracking branch 'origin/main' into docs-enablement

773877d

Merge remote-tracking branch 'origin/main' into docs-enablement

2a9a777

review feedback edits

6eb0166

changes to aim at contributors

5c1a9b7

correct doc channel

5493219

kaitlynmichael added 2 commits July 27, 2026 13:37

add concrete steps

0527a39

remove dod page

657b103

andy-stark-redis reviewed Jul 28, 2026

View reviewed changes

kaitlynmichael closed this Jul 28, 2026

github-actions Bot mentioned this pull request Aug 4, 2026

Onboarding guide #3748

Open


		## 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.

		@@ -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.

	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.
	Base style: [Google developer documentation style](https://developers.google.com/style); fall back to the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) where Google is silent. Follow these on every docs change. AI tools working in this repo inherit these rules automatically.


		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 `<topic>` 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.

Uh oh!

Conversation

kaitlynmichael commented Jul 21, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mich-elle-luna left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 27, 2026

🧠 Redis Memory

Uh oh!

github-actions Bot commented Jul 27, 2026

🧠 Redis Memory

Uh oh!

github-actions Bot commented Jul 27, 2026

🧠 Redis Memory

Uh oh!

andy-stark-redis left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kaitlynmichael commented Jul 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kaitlynmichael commented Jul 21, 2026 •

edited by cursor Bot

Loading