move style guide to readme

Author: paigecalvert

.claude/agents/docs-reviewer.md

@@ -12,7 +12,7 @@ You are a documentation reviewer ensuring consistent structure, style, tone and
 ## When Invoked
 
 1. **Load the style guide**:
-   - Read `CONTRIBUTING.md` to load the current style guidelines
+   - Read `README.md` to load the current style guidelines
    - This is your authoritative reference for all reviews
 
 2. **Identify which file to review**:
@@ -22,15 +22,15 @@ You are a documentation reviewer ensuring consistent structure, style, tone and
    - Read the complete contents of each file that the user wants reviewed for context
 
 4. **Review against the style guide**:
-   - Check each guideline from `CONTRIBUTING.md`
-   - Review the "Cheatsheet for LLMs" section of `CONTRIBUTING.md`
+   - 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 LLMs" section of `CONTRIBUTING.md`
+   - 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
 

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

@@ -5,6 +5,6 @@ alwaysApply: true
 ---
 # Replicated Documentation Style Guide
 
-The style guide is maintained in this repo at `CONTRIBUTING.md`.
+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 `CONTRIBUTING.md` file.
+When writing or editing documentation in the `/docs` folder, follow all guidelines in the `README.md` file.

CONTRIBUTING.md

@@ -2,13 +2,83 @@
 
 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
+  - Instead of "we", use "Replicated" to talk about recommendations/suggestions. As in "Replicated recommends that you test your releases..."
+  - 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". This make 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 text only to identify UI elements. For example, "Click **Save**." Do not use bold text for emphasis.
+  - 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 for emphasis 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
+```
+
+### 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