Merge pull request #3176 from replicatedhq/cursor-rules

Swap gerunds for present tense verbs and add link-updating script

Author: paigecalvert

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

@@ -0,0 +1,62 @@
+---
+description: 
+globs: 
+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." 
+

docs/enterprise/auth-changing-passwords.md

@@ -1,4 +1,4 @@
-# Changing an Admin Console Password
+# Change an Admin Console Password
 
 When you install for the first time with Replicated kURL, the Replicated KOTS Admin Console is secured with a single shared password that is set automatically for all users. Replicated recommends that you change this to a new, unique password for security purposes as this automated password is displayed to the user in plain text.
 
@@ -7,7 +7,7 @@ The Admin Console password is salted and one-way hashed using bcrypt. The irreve
 For more information about bcrypt, see [bcrypt](https://en.wikipedia.org/wiki/Bcrypt) on Wikipedia.
 
 :::note
-Users with Identity Provider (IDP) access cannot change their password using this procedure. If an attempt is made, IDP users receive a message in the user interface to contact the identity service provider to change their password. For more information about resetting an IDP user password, see [Resetting Authentication](auth-identity-provider#resetting-authentication) in _Using an Identity Provider for User Access (Beta)_.
+Users with Identity Provider (IDP) access cannot change their password using this procedure. If an attempt is made, IDP users receive a message in the user interface to contact the identity service provider to change their password. For more information about resetting an IDP user password, see [Resetting Authentication](auth-identity-provider#resetting-authentication) in _Use an Identity Provider for User Access (Beta)_.
 :::
 
 To change your Admin Console password:

docs/enterprise/auth-configuring-rbac.md

@@ -1,4 +1,4 @@
-# Configuring Role-based Access Control (Beta)
+# Configure Role-based Access Control (Beta)
 
 You can regulate access to the Replicated KOTS Admin Console resources based on the roles of individual users within your organization.
 

docs/enterprise/auth-identity-provider.md

@@ -1,4 +1,4 @@
-# Using an Identity Provider for User Access (Beta)
+# Use an Identity Provider for User Access (Beta)
 
 When you install an application for the first time, the Replicated KOTS Admin Console is secured with a single shared password for all users. It is possible to further configure the Admin Console to authenticate users with your organization's user management system. This feature is only available for licenses that have the Replicated identity service feature enabled.
 

docs/enterprise/cluster-management-add-nodes.md

@@ -1,6 +1,6 @@
 import KurlAvailability from "../partials/kurl/_kurl-availability.mdx"
 
-# Adding Nodes to kURL Clusters
+# Add Nodes to kURL Clusters
 
 <KurlAvailability/>
 

docs/enterprise/delete-admin-console.md

@@ -1,4 +1,4 @@
-# Deleting the Admin Console and Removing Applications
+# Delete the Admin Console and Remove Applications
 
 This topic describes how to remove installed applications and delete the Replicated KOTS Admin Console. The information in this topic applies to existing cluster installations with KOTS.
 
@@ -81,4 +81,4 @@ To completely delete the Admin Console from an existing cluster:
    kubectl delete clusterrolebinding kotsadm-rolebinding
    ```
 
-1. (Optional) To uninstall the KOTS CLI, see [Uninstall](https://docs.replicated.com/reference/kots-cli-getting-started#uninstall) in _Installing the KOTS CLI_.   
+1. (Optional) To uninstall the KOTS CLI, see [Uninstall](https://docs.replicated.com/reference/kots-cli-getting-started#uninstall) in _Installing the KOTS CLI_.   

docs/enterprise/embedded-manage-nodes.mdx

@@ -1,6 +1,6 @@
 import HaArchitecture from "../partials/embedded-cluster/_multi-node-ha-arch.mdx"
 
-# Managing Multi-Node Clusters with Embedded Cluster
+# Manage Multi-Node Clusters with Embedded Cluster
 
 This topic describes managing nodes in clusters created with Replicated Embedded Cluster, including how to add nodes and enable high-availability for multi-node clusters.
 
@@ -36,7 +36,7 @@ To add nodes to a cluster:
 
          1. Log in to the Admin Console.
 
-         1. If you promoted a new release that configures the `roles` key in the Embedded Cluster Config, update the instance to the new version. See [Performing Updates in Embedded Clusters](/enterprise/updating-embedded).
+         1. If you promoted a new release that configures the `roles` key in the Embedded Cluster Config, update the instance to the new version. See [Perform Updates in Embedded Clusters](/enterprise/updating-embedded).
 
          1. Go to **Cluster Management > Add node** at the top of the page.
 
@@ -50,7 +50,7 @@ To add nodes to a cluster:
 
      * If the Embedded Cluster Config [roles](/reference/embedded-config#roles) key is not configured, all new nodes joined to the cluster are assigned the `controller` role by default. The `controller` role designates nodes that run the Kubernetes control plane. Controller nodes can also run other workloads, such as application or Replicated KOTS workloads.
 
-     * Roles are not updated or changed after a node is added. If you need to change a node’s role, reset the node and add it again with the new role.
+     * Roles are not updated or changed after a node is added. If you need to change a node's role, reset the node and add it again with the new role.
 
      * For multi-node clusters with high availability (HA), at least three `controller` nodes are required. You can assign both the `controller` role and one or more `custom` roles to the same node. For more information about creating HA clusters with Embedded Cluster, see [Enable High Availability for Multi-Node Clusters (Alpha)](#ha) below.
 

docs/enterprise/embedded-tls-certs.mdx

@@ -1,4 +1,4 @@
-# Updating Custom TLS Certificates in Embedded Cluster Installations
+# Update Custom TLS Certificates in Embedded Cluster Installations
 
 This topic describes how to update custom TLS certificates in Replicated Embedded Cluster installations.
 

docs/enterprise/gitops-managing-secrets.mdx

@@ -1,6 +1,6 @@
 import GitOpsNotRecommended from "../partials/gitops/_gitops-not-recommended.mdx"
 
-# Managing Secrets with KOTS Auto-GitOps (Alpha)
+# Manage Secrets with KOTS Auto-GitOps (Alpha)
 
 <GitOpsNotRecommended/>
 

docs/enterprise/gitops-workflow.mdx

@@ -13,7 +13,7 @@ If you have more than one application installed, you can selectively enable Auto
 
 After enabling the Auto-GitOps workflow for an application, the Admin Console makes your first commit with the latest available version in the Admin Console. The latest available version is often the current version that is deployed. Subsequently, the Admin Console makes separate commits with any available updates.
 
-If you configure automatic updates for the application, any updates from your vendor are automatically committed to your Git repository. For more information about configuring automatic updates, see [Configuring Automatic Updates](/enterprise/updating-apps).
+If you configure automatic updates for the application, any updates from your vendor are automatically committed to your Git repository. For more information about configuring automatic updates, see [Configure Automatic Updates](/enterprise/updating-apps).
 
 You can change your GitOps settings or disable Auto-GitOps at any time from the **GitOps** tab in the Admin Console.