diff --git a/.claude/agents/docs-reviewer.md b/.claude/agents/docs-reviewer.md new file mode 100644 index 0000000000..ad88c10eb9 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/.cursor/rules/docs-style-guide.mdc b/.cursor/rules/docs-style-guide.mdc index b16f1acd93..fa4846990f 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 `README.md`. +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/README.md b/README.md index 1baf06e9b9..4f445d9cd9 100644 --- a/README.md +++ b/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 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