From d63a846a9e4ed5f5dee16d6f3c490e0b65b1934f Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Tue, 16 Dec 2025 14:17:11 -0700 Subject: [PATCH 1/7] wip add claude subagent for docs reviews --- .claude/agents/docs-reviewer.md | 98 +++++++++++++++++ .cursor/rules/docs-style-guide.mdc | 60 +---------- CONTRIBUTING.md | 67 ++++++++++++ docs/templates/procedure.md | 90 ---------------- docs/templates/process-multiple-procedures.md | 102 ------------------ docs/templates/release-notes.md | 34 ------ docs/test-doc-review.mdx | 64 +++++++++++ 7 files changed, 233 insertions(+), 282 deletions(-) create mode 100644 .claude/agents/docs-reviewer.md create mode 100644 CONTRIBUTING.md delete mode 100644 docs/templates/procedure.md delete mode 100644 docs/templates/process-multiple-procedures.md delete mode 100644 docs/templates/release-notes.md create mode 100644 docs/test-doc-review.mdx diff --git a/.claude/agents/docs-reviewer.md b/.claude/agents/docs-reviewer.md new file mode 100644 index 0000000000..d145cc8c5e --- /dev/null +++ b/.claude/agents/docs-reviewer.md @@ -0,0 +1,98 @@ +--- +name: docs-reviewer +description: Reviews technical documentation for style, word choice, tone/voice, and content structure. Use immediately after writing or editing docs for Replicated. +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 `CONTRIBUTING.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 they want reviewed for context + +4. **Review against the style guide**: + - Check each guideline from `CONTRIBUTING.md` + - Review the "Cheatsheet for LLMs" section of `CONTRIBUTING.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` + - 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. +``` + +## 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 \ No newline at end of file diff --git a/.cursor/rules/docs-style-guide.mdc b/.cursor/rules/docs-style-guide.mdc index b16f1acd93..2c03d2e572 100644 --- a/.cursor/rules/docs-style-guide.mdc +++ b/.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 `CONTRIBUTING.md`. +When writing or editing documentation in the `/docs` folder, follow all guidelines in the `CONTRIBUTING.md` file. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..600a21a7f1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,67 @@ +# Replicated Documentation 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. + +## Style Guide Summary + +This 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 LLMs + +When generating content for Replicated Docs with LLMs, add the following to the context window: + +``` +- Refer to the style guidelines in this repo at `CONTRIBUTING.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 +``` diff --git a/docs/templates/procedure.md b/docs/templates/procedure.md deleted file mode 100644 index 6ae5dff785..0000000000 --- a/docs/templates/procedure.md +++ /dev/null @@ -1,90 +0,0 @@ -# Page Title (Use a gerund. For example, "Creating...") - - - -[Introductory paragraph stating the business reason - what and why - a user would want to do this procedure.] - -**Prerequisites** - -Complete the following items before you perform this task: -* First item -* Second item - -To [do this task]: [For example, "To create a customer license:"] - -1. Log in to the [vendor portal](https://vendor.replicated.com), and click **Customer > Create Customer**. - - [Optional: Include a results step. Use only when a result is not obvious, such as in a complex UX flow like GitOps. For example, "A list of your applications displays and shows the status of GitOps integration for each application."] - -1. Edit the fields: - - - - - - - - - - - - - - -
NameDescription
Field NameExample description: The type of customer is used solely for reporting purposes. Their access to your app is not affected by the type you assign to them. Options: Development, Trial, Paid, Community. Default: Trial. For more information, see Creating a Customer.
- - - -1. Run the following command to export the blah blah blah: - - ``` - kubectl kots pull UPSTREAM_URI --cluster CLUSTER_NAME - ``` - - Replace: - - - UPSTREAM_URI: With the URI for the application. - - CLUSTER_NAME: With the name of the kubeconfig cluster. - - - [Use a bulleted list for the placeholder text definitions unless you feel the list is too long and that a table would be cleaner. If you need to use a table, use the following table format: - - - - - - - - - - - - - - -
ReplaceWith
UPSTREAM_URIThe URI for the application.
CLUSTER_NAMEThe name of the kubeconfig cluster.
- -1. Click **Save Changes**. - -## Next Step - -[Describe and link to the next task.] - -## Related Topics - - - -[Example Related Topic Title](https://docs.replicated.com) diff --git a/docs/templates/process-multiple-procedures.md b/docs/templates/process-multiple-procedures.md deleted file mode 100644 index 442171dc9b..0000000000 --- a/docs/templates/process-multiple-procedures.md +++ /dev/null @@ -1,102 +0,0 @@ -# Page Title (Use a gerund. For example, "Creating...") - - - -[Introductory paragraph stating the business reason why a user would want to do this process/workflow or tutorial.] - -## Prerequisites - -These actions or items must be complete before you perform this task: -* First item -* Second item - -## Task Heading (Start with verb. For example, "Create a Customer License") - -[Introductory sentence or two to explain the “what“ and “why“ of the task.] - -To [do this task]: [For example, "To create a customer license:"] - -1. Log in to the [vendor portal](https://vendor.replicated.com), and click **Customer > Create Customer**. - - [Optional: include a results step. Use only when a result is not obvious. For example, "The Create a new customer page opens."] - -1. Edit the fields: - - - - - - - - - - - - - - -
NameDescription
Field Name[Example description: The type of customer is used solely for reporting purposes. Their access to your app is not affected by the type you assign to them. Options: Development, Trial, Paid, Community. Default: Trial. For more information, see LINK.]
Field NameSpecifies the...
- -1. Run the following command to export the blah blah blah: - - ``` - kubectl kots pull UPSTREAM_URI --cluster CLUSTER_NAME - ``` - Replace: - - - UPSTREAM_URI: With the URI for the application. - - CLUSTER_NAME: With the name of the kubeconfig cluster. - - - [Use a bulleted list for the placeholder text definitions unless you feel the list is too long and that a table would be cleaner. If you need to use a table, use the following table format: - - - - - - - - - - - - - - -
ReplaceWith
UPSTREAM_URIThe URI for the application.
CLUSTER_NAMEThe name of the kubeconfig cluster.
- -1. Click **Save Changes**. - -## (Optional) Task Heading 2 - - - -[Introductory sentence or two to explain the “what“ and “why“ of the task. You can tell the user that the previous task must be completed first. For example: "After you create a blah blah, you can configure the... This helps you..."] - -To [do this task]: - -1. Step -1. Step - - -## Task Heading 3 - -[Introductory sentence or two to explain the “what“ and “why“ of the task. You can tell the user that the previous task must be completed first. For example: "After you create a blah blah, you can configure the... This helps you..."] - -To [do this task]: - -1. Step -1. Step - -## Related Topics - - - -[My Topic Title](https://docs.replicated.com) diff --git a/docs/templates/release-notes.md b/docs/templates/release-notes.md deleted file mode 100644 index 4d3ae97e2d..0000000000 --- a/docs/templates/release-notes.md +++ /dev/null @@ -1,34 +0,0 @@ -# Product Name Release Notes - -## vX.X.X - -Release Date: Month Day, Year - -### Kubernetes Compatibility - -This release is compatible with Kubernetes vX.X, vX.Y, and vX.Z. - -### Security Fixes - -* Fix 1 -* Fix 2 - -### New Features - -* New feature 1 -* New feature 2 - -### Improvements - -* Improvement 1 -* Improvement 2 - -### Bug Fixes - -* Bug 1 -* Bug 2 - -### Known Issues - -* Known issue 1 -* Known issue 2 diff --git a/docs/test-doc-review.mdx b/docs/test-doc-review.mdx new file mode 100644 index 0000000000..9ef3fb375d --- /dev/null +++ b/docs/test-doc-review.mdx @@ -0,0 +1,64 @@ +--- +title: How to Configure Your Application Settings? +--- + +# How to Configure Your Application Settings? + +## Overview + +We're excited to help you get started with configuring your application! This guide will walk you through the simple and easy process of setting up your application. + +Currently, the configuration process is the best way to customize your application. Let's begin! + +## Prerequisites + +Before you start, make sure you have: +- An active account +- Access to the Admin Console + +## Configuration Steps + +1. First, let's navigate to the Settings page in your Admin Console +2. We recommend that you simply click the Save button to save your changes +3. The configuration will be saved and will be applied to your application +4. Currently, you can modify these settings at any time by going back to the Settings page + +You can read more about advanced settings [here](https://example.com) if you need additional customization. + +:::note +The system is designed to automatically validate your settings. This is the easiest way to ensure everything works correctly! +::: + +## Troubleshooting + +**What should I do if the settings won't save?** + +If the settings won't save, we suggest that you try the following: + +- Click the Refresh button in your browser +- Check that all required fields are filled out +- Currently, there's a known issue with certain browsers + +For more information, see our troubleshooting guide. + +## Best Practices + +Here are some best practices to follow: + +1. Always click Save after making changes +2. We recommend backing up your configuration regularly +3. You should never use special characters in field names +4. Simply review your settings before deploying + +## Additional Resources + +At this time, you can find more information in the following locations: + +- Check out [this page](https://example.com) for details +- New features will be added in the next release +- The documentation can be found [in our knowledge base](https://example.com) + +## Conclusion + +Now that you've completed the configuration, your application is ready to use! We hope this guide was helpful. If you have any questions, feel free to reach out to our support team. + From c3ff3d9e634d570db12b938ea134bcfb58b4f918 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 17 Dec 2025 08:35:52 -0700 Subject: [PATCH 2/7] remove test doc --- docs/test-doc-review.mdx | 64 ---------------------------------------- 1 file changed, 64 deletions(-) delete mode 100644 docs/test-doc-review.mdx diff --git a/docs/test-doc-review.mdx b/docs/test-doc-review.mdx deleted file mode 100644 index 9ef3fb375d..0000000000 --- a/docs/test-doc-review.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: How to Configure Your Application Settings? ---- - -# How to Configure Your Application Settings? - -## Overview - -We're excited to help you get started with configuring your application! This guide will walk you through the simple and easy process of setting up your application. - -Currently, the configuration process is the best way to customize your application. Let's begin! - -## Prerequisites - -Before you start, make sure you have: -- An active account -- Access to the Admin Console - -## Configuration Steps - -1. First, let's navigate to the Settings page in your Admin Console -2. We recommend that you simply click the Save button to save your changes -3. The configuration will be saved and will be applied to your application -4. Currently, you can modify these settings at any time by going back to the Settings page - -You can read more about advanced settings [here](https://example.com) if you need additional customization. - -:::note -The system is designed to automatically validate your settings. This is the easiest way to ensure everything works correctly! -::: - -## Troubleshooting - -**What should I do if the settings won't save?** - -If the settings won't save, we suggest that you try the following: - -- Click the Refresh button in your browser -- Check that all required fields are filled out -- Currently, there's a known issue with certain browsers - -For more information, see our troubleshooting guide. - -## Best Practices - -Here are some best practices to follow: - -1. Always click Save after making changes -2. We recommend backing up your configuration regularly -3. You should never use special characters in field names -4. Simply review your settings before deploying - -## Additional Resources - -At this time, you can find more information in the following locations: - -- Check out [this page](https://example.com) for details -- New features will be added in the next release -- The documentation can be found [in our knowledge base](https://example.com) - -## Conclusion - -Now that you've completed the configuration, your application is ready to use! We hope this guide was helpful. If you have any questions, feel free to reach out to our support team. - From 6934ae5d5edfe61d4d5abacd4bac201d9ad550c7 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 17 Dec 2025 08:37:49 -0700 Subject: [PATCH 3/7] edit contributing guide --- CONTRIBUTING.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 600a21a7f1..00daf6cb73 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,10 @@ -# Replicated Documentation Style Guide +# Contribute to Replicated Documentation -The Replicated docs use the Google Developer Docs Style Guide: https://developers.google.com/style/ +## Style Guide -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 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. -## Style Guide Summary - -This 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: +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 From 8142763209bf447d17ab6287c62a6cbbde92e968 Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Wed, 17 Dec 2025 08:41:12 -0700 Subject: [PATCH 4/7] edit agent description --- .claude/agents/docs-reviewer.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/agents/docs-reviewer.md b/.claude/agents/docs-reviewer.md index d145cc8c5e..d5bc3efea9 100644 --- a/.claude/agents/docs-reviewer.md +++ b/.claude/agents/docs-reviewer.md @@ -1,6 +1,6 @@ --- name: docs-reviewer -description: Reviews technical documentation for style, word choice, tone/voice, and content structure. Use immediately after writing or editing docs for Replicated. +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 --- @@ -19,7 +19,7 @@ You are a documentation reviewer ensuring consistent structure, style, tone and - Ask the user which file to review if not already specified 3. **Read full context**: - - Read the complete contents of each file that they want reviewed for context + - 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` From de9aa7d913242e9f3ebccd39d61473f69322db8c Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 18 Dec 2025 08:44:49 -0700 Subject: [PATCH 5/7] move style guide to readme --- .claude/agents/docs-reviewer.md | 8 +-- .cursor/rules/docs-style-guide.mdc | 4 +- CONTRIBUTING.md | 65 ----------------------- README.md | 84 +++++++++++++++++++++++++++--- 4 files changed, 83 insertions(+), 78 deletions(-) delete mode 100644 CONTRIBUTING.md diff --git a/.claude/agents/docs-reviewer.md b/.claude/agents/docs-reviewer.md index d5bc3efea9..bf08f91633 100644 --- a/.claude/agents/docs-reviewer.md +++ b/.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 diff --git a/.cursor/rules/docs-style-guide.mdc b/.cursor/rules/docs-style-guide.mdc index 2c03d2e572..fa4846990f 100644 --- a/.cursor/rules/docs-style-guide.mdc +++ b/.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. \ No newline at end of file +When writing or editing documentation in the `/docs` folder, follow all guidelines in the `README.md` file. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 00daf6cb73..0000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,65 +0,0 @@ -# Contribute to Replicated Documentation - -## 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 LLMs - -When generating content for Replicated Docs with LLMs, add the following to the context window: - -``` -- Refer to the style guidelines in this repo at `CONTRIBUTING.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 -``` diff --git a/README.md b/README.md index 1baf06e9b9..0e54908407 100644 --- a/README.md +++ b/README.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 From c851af4f675ae6c499d306889aaff5d22280531b Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 18 Dec 2025 09:15:59 -0700 Subject: [PATCH 6/7] edits to style guide and docs-reviewer agent --- .claude/agents/docs-reviewer.md | 6 ++++++ README.md | 10 ++++++++-- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/.claude/agents/docs-reviewer.md b/.claude/agents/docs-reviewer.md index bf08f91633..ad88c10eb9 100644 --- a/.claude/agents/docs-reviewer.md +++ b/.claude/agents/docs-reviewer.md @@ -80,6 +80,12 @@ Issue 3 - 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 diff --git a/README.md b/README.md index 0e54908407..6f9d9d9486 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,11 @@ The following is a summary of the most important elements of our style guide, pl - 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 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 @@ -64,9 +68,11 @@ When generating content for Replicated Docs with LLMs, add the following to the ```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 +- 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 +- ``` ### Use the @doc-reviewer Claude Subagent From a6267dedca3e8a4b41577b8ceaf2a86e866616bd Mon Sep 17 00:00:00 2001 From: Paige Calvert Date: Thu, 18 Dec 2025 09:24:06 -0700 Subject: [PATCH 7/7] edits to style guide --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 6f9d9d9486..4f445d9cd9 100644 --- a/README.md +++ b/README.md @@ -25,12 +25,12 @@ The following is a summary of the most important elements of our style guide, pl - 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 "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". This make the docs more suitable for a global audience + - 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. @@ -72,7 +72,7 @@ When generating content for Replicated Docs with LLMs, add the following to the - 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