Merge pull request #3721 from replicatedhq/claude-docs-review-skill

Add claude subagent for docs reviews

Author: paigecalvert

.claude/agents/docs-reviewer.md

@@ -0,0 +1,104 @@
+---
+name: docs-reviewer
+description: Reviews technical documentation for style, word choice, tone/voice, and content structure. Use after writing or editing Replicated docs.
+tools: Read, Grep, Glob, Terminal
+model: inherit
+---
+
+# Your Role
+
+You are a documentation reviewer ensuring consistent structure, style, tone and voice, and formatting across the documentation. You enforce the Replicated Documentation Style Guide.
+
+## When Invoked
+
+1. **Load the style guide**:
+   - Read `README.md` to load the current style guidelines
+   - This is your authoritative reference for all reviews
+
+2. **Identify which file to review**:
+   - Ask the user which file to review if not already specified
+
+3. **Read full context**:
+   - Read the complete contents of each file that the user wants reviewed for context
+
+4. **Review against the style guide**:
+   - Check each style guideline from `README.md`
+   - Review the "Cheatsheet for Generating Content with LLMs" section of `README.md`
+   - Review only the modified content (or entire file if newly created)
+
+5. **Generate and output report**:
+   - Output the report directly
+   - You may include 0 to 7 issues in the report
+   - If you identify more than 7 issues, tell the user that you found more issues than are listed in this report, and they should review the rest of their doc for similar issue patterns
+   - Prioritize reporting on issues that are called out in the "Cheatsheet for Generating Content with LLMs" section of `README.md`
+   - Use the Report Structure and Issue Format specified below
+   - Refer to the Report Tone Guidelines below
+
+## Report Structure
+
+Use this structure for the docs review report (do not include any additional sections or summaries):
+
+```
+File(s) Reviewed: [filename(s)]
+
+## Style Guide Issues
+
+[List each issue individually using the Issue Format below]
+```
+
+## Issue Format
+
+In the report, you must list each issue individually using this format:
+
+```
+[Issue number]
+- "[exact text from the doc]"
+- Location: [filename], line [number] 
+- Suggestion: "[proposed replacement text]" or [explanation of change]
+- Explanation: reasoning behind the suggestion, based on the style guide
+```
+
+## Example of Correct Report Format
+
+```
+File(s) Reviewed: example.md, example-2.md
+
+Issue 1
+- "In the future, we will release a version that adds that functionality."
+- Location: example.md, line 23 
+- Suggestion: Remove this sentence
+- Explanation: Avoid time-bound terminology like "currently", "new", "at this time", and "now". Instead, write timeless documentation that makes no assumptions about a reader's prior knowledge.
+
+Issue 2
+- "## Best Practices"
+- Location: example.md, line 67 
+- Suggestion: Carefully review this section and consider removing it
+- Explanation: LLMs often add Best Practices sections that are redundant with existing content on the page. Is this Best Practices section adding valuable new information, or can it be removed?
+
+Issue 3
+- "If the settings won't save, we suggest that you try the following:"
+- Location: example-2.md, line 5 
+- Suggestion: "If the settings won't save, Replicated suggests that you try the following:"
+- Explanation: Instead of "we", use "Replicated" to talk about recommendations/suggestions.
+
+Issue 4
+- Multiple subsections use the same information repeated in different ways (e.g., the "Field Reference" section starting at line 80 repeats information already provided in the "Configuration Structure" section starting at line 35)
+- Location: example.md, lines 35-79 and lines 80-219
+- Suggestion: Consider consolidating these sections to avoid repetition
+- Explanation: Don't repeat the same information multiple times. Focus on being concise and using as few words as possible to get the point across.
+```
+
+## Report Tone Guidelines
+
+Do:
+- Use the report format outlined and add helpful explanations for your suggestions based on the style guide
+- Use a friendly, collaborative, helpful tone
+- Use terms like "suggest," "issue," "consider," or "update"
+
+Do not:
+- Use words like "critical," "violation," "must," "error," "extensive," or "prohibited"
+- Group issues into summary categories or provide overviews
+- Include "Recommended Action," "Recommendation," or "Summary" sections beyond what's in the Report Structure
+- Provide example rewrites of entire sections
+- Use checkmarks (✅), X marks (❌), or other status indicators
+- Say things like "needs complete rewrite" or assess severity

.cursor/rules/docs-style-guide.mdc

@@ -1,62 +1,10 @@
 ---
-description: 
-globs: 
+description: Replicated Documentation Style Guide
+globs: ["docs/**/*.md", "docs/**/*.mdx"]
 alwaysApply: true
 ---
 # Replicated Documentation Style Guide
 
-## Overview
-
-This set of rules provides guidelines for writing clear and consistent product documentation for the Replicated Platform.
-
-## General Principles
-
-### Tone and Voice
-- Use active voice instead of passive voice
-- Use the second person "you" to address the reader
-- Never use "we" or "let's"
-- Write in a friendly tone without using slang, jargon, or frivolous words.
-
-### Accessibility and Inclusivity
-- Write for a global audience by avoiding culturally-specific references, jargon, and figures of speech.
-- In HTML, use semantic tagging.
-- Avoid unnecessary font formatting.
-- Avoid large blocks of text by using short paragraphs, headings, and lists
-- Use shorter sentences. Try to use fewer than 26 words per sentence.
-
-### Excessive Claims, Future Claims, and Marketing-Focused Language
-- Never use phrases like "simply" or "easily" in a procedure.
-- Avoid superlatives like best, worst, simplest, fastest, never, and always
-- Don't make any claims about a product that the user would not be able to easily verify.
-
-### Timeless Documentation
-- Avoid time-bound terminology like "currently", "new", "at this time", and "now". Instead, write timeless documentation that makes no assumptions about a reader's prior knowledge.
-
-## Formatting
-
-### Text Formatting
-- Use bold for UI elements
-- Use bold for navigation steps in a UI, such as **Releases > Create Release**.
-- Use italics to draw attention to a word or phrase, such as when defining the term for the first time
-
-### Capitalization
-- Use title case for titles and headings
-- Use all caps with underscores between words for placeholder text
-- Avoid all caps outside of placeholder text and code examples
-
-### Symbols
-- Avoid using the ampersand symbol (&) except when describing UI elements, writing code examples, or in tables where space is limited
-
-### Punctuation
-- Avoid semicolons
-- Avoid exclamation marks
-- Avoid question marks
-
-## Linking
-
-### Cross-references
-- A good cross-reference describes what information the reader can expect to learn, as well as the exact title (and location) of the page they will be taken to.
-- Do not embed links within a sentence.
-- Use the following format for cross references: "For more information about X, see [Topic Title](mdc:url)."
-- For links to other websites outside of docs.replicated.com, use the following format: "For more information about X, see [Topic Title](mdc:url) in the Company Name documentation." 
+The style guide is maintained in this repo at `README.md`.
 
+When writing or editing documentation in the `/docs` folder, follow all guidelines in the `README.md` file.

README.md

@@ -2,13 +2,89 @@
 
 Welcome to the repository for the [Replicated documentation site](https://docs.replicated.com/).
 
-## Contribute to the Replicated Docs
-
-This repository has been made public so that vendors and the open-source community can contribute to the content using the following methods:
-
-- **Submit a PR** You can submit a PR directly from a specific topic in the documentation by clicking the **Create pull request or raise issue on GitHub** at the bottom of the page. This method lets you edit the content directly and commit your changes on a new branch. After submitting your proposed changes, the Replicated team will verify the accuracy of the changes and perform an editorial review. If the PR is approved, it will be merged directly into the main branch.
-
-- **Open a Github Issue** - To open a GitHub issue for this repository, click the Issues tab and click **New Issue**. This method may be more useful when you want to report a bug specifically for the documentation. If you are having an issue with the product itself, we encourage you to report it to us in a support issue submitted in the vendor portal.
+## Contribute to Replicated Docs
+
+This repository has been made public so that the Replicated community can contribute to the content.
+
+### Submit a PR
+
+You can submit a PR directly from a specific topic in the documentation by clicking **Propose Changes** at the bottom of the page. This method lets you edit the content directly and commit your changes on a new branch. After submitting your proposed changes, the Replicated Docs team will verify the accuracy of the changes and perform an editorial review. If the PR is approved, it will be merged directly into the main branch.
+
+### Open a Github Issue
+
+You can open a GitHub issue in this repo to provide feedback or report a bug for the documentation. To open an issue, either go to **Issues > New Issue** in this repo in GitHub, or click **Provide Feedback** at the bottom of any page in the documentation.
+
+If you are having an issue with the product itself, report it to the Replicated team in a support issue submitted in the Vendor Portal.
+
+## Style Guide
+
+The Replicated docs use the Google Developer Docs Style Guide: https://developers.google.com/style/. Refer to the Google Developer Docs Style Guide if you have a style guide question that's not covered in the Style Guide Summary in this document.
+
+The following is a summary of the most important elements of our style guide, plus some house rules that aren't captured or differ from what's in the Google Developer Docs Style Guide:
+
+- Word Choice, Tone, and Voice:
+  - Use active voice
+  - Use the second person "you" to address the reader. Never use "let's" or "we" to refer to an action that the user is doing
+  - Use "Replicated" instead of "we" to talk about recommendations/suggestions. As in "Replicated recommends that you test your releases..." and not "we recommend"
+  - Use present tense (for example, use "returns" and not "will return")
+  - Write in a friendly tone without using slang, jargon, or frivolous words
+  - Avoid marketing language that is overly promotional
+  - Avoid terms like "simple" or "easy"
+  - Use common words. Don't use words like "utilize" or "leverage" when you mean "use". Using common words makes the docs more suitable for a global audience
+  - Try to use fewer than 26 words per sentence
+  - Avoid time-bound terminology like "currently", "new", "at this time", and "now". Instead, write timeless documentation that makes no assumptions about a reader's prior knowledge.
+
+- Formatting:
+  - Use bold and italic text sparingly.
+    - Bold text is primarily used to identify UI elements. For example, "Click **Save**." 
+    - Do not use bold text to emphasize important content. Instead, if discoverability is a concern, consider how the content could be reorganized or how you could use clearer headings. 
+    - It's okay to use bold text for introducing an example (`**Example:**`) or for run-in headings in unordered lists (`* **Item 1:** Description`)
+  - Use colons instead of dashes for run-in headings in description lists (`- Item 1: Description`, not `- Item 1 - Description`)
+  - Use title case for titles and headings
+  - Use a bare infinitive verb form for how-to titles/headings. As in, use "Create a Release" instead of "Creating a Release"
+  - Procedural/how-to content must use numbered steps. For one-step procedures, use a bullet point. See https://developers.google.com/style/procedures#single-step-procedures for examples
+  - Use the following formats for cross references:
+    - "For more information about X, see [Topic Title](mdc:url)"
+    - "For more information about X, see [Section Heading](mdc:url#section-heading) in _Topic Title_."
+    - "For more information about X, see [Section Heading](#section-heading) in this document."
+  - We use "Note" and "Important" admonitions.
+    - Notes are for informational asides. Only use notes if the info is relevant but not required to succeed in whatever the user is doing right now. Don't use notes to state expected results or to include information that simply describes what precedes.
+      ```md
+      :::note
+      note content
+      :::
+      ```
+    - Important admonitions are to provide cautionary/warning messages.
+      ```md
+      :::impotant
+      important content
+      :::
+      ```
+
+### Cheatsheet for Generating Content with LLMs
+
+When generating content for Replicated Docs with LLMs, add the following to the context window:
+
+```md
+- Refer to the style guidelines in this repo at `README.md`
+- Don't add Troubleshooting, Best Practices, Conclusion, Summary, or Next Steps sections unless specifically asked
+- Never use bold text to emphasize important information or as section/category headings
+- Don't repeat the same information mutiple times. Focus on being concise and using as few words as possible to get the point across
+- Use paragraphs instead of bulleted lists unless specifically asked
+- Don't number the items in unordered lists. Numbered lists are reserved for step-by-step procedures
+- Limit the use of notes and asides
+```
+
+### Use the @doc-reviewer Claude Subagent
+
+The `@docs-reviewer` subagent reviews documentation files against this style guide and identifies issues with suggestions for fixes. You can use it to help you catch common style problems before submitting PRs.
+
+To use it, invoke `@docs-reviewer` in Claude Desktop or Claude Code and specify the file you want reviewed.
+
+For example:
+```
+@docs-reviewer please review docs/example.md
+```
 
 ## Folder Structure and Sidebar