From 7fa48db8a8beb341027211c7f9a9d715a40f3a88 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Tue, 19 May 2026 16:32:34 -0400 Subject: [PATCH 1/6] style guide improvements --- StyleGuide.md | 131 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 116 insertions(+), 15 deletions(-) diff --git a/StyleGuide.md b/StyleGuide.md index 05b31906b98..d4b49f1627c 100644 --- a/StyleGuide.md +++ b/StyleGuide.md @@ -13,6 +13,9 @@ Included in this guide: - [CockroachDB products](#cockroachdb-products) - [CockroachDB versions](#cockroachdb-versions) - [Third-party products](#third-party-products) + - ["Directory" vs "folder"](#directory-vs-folder) + - ["Legacy" vs "deprecated"](#legacy-vs-deprecated) + - ["In" vs "on" a cluster](#in-vs-on-a-cluster) - [AI](#ai) - [Inclusivity](#inclusivity) - [Avoid ableist language](#avoid-ableist-language) @@ -53,7 +56,7 @@ CockroachDB docs should be helpful, humble, positive, friendly, and free from hy ### Perspective and voice -For instructions, use the imperative present tense, aka "[imperative mood](https://www.grammar-monster.com/glossary/imperative_mood.htm)." The second-person subject ("you") is implied and can be omitted. +For tasks, use the imperative present tense, aka "[imperative mood](https://www.grammar-monster.com/glossary/imperative_mood.htm)." The second-person subject ("you") is implied and can be omitted. **Examples:** @@ -93,7 +96,7 @@ Use active instead of passive voice. - **Avoid:** Additional options can be specified. **Prefer:** You can specify additional options. -Use concise, direct language. Cut unnecessary words unless a conversational tone is intentional (for example, in tutorials). If a feature or concept is difficult to describe clearly or concisely, consider using an [example](#examples) or [image](#images) to complement the text. +Use concise, direct language. Cut unnecessary words unless a conversational tone is intentional (for example, in tutorials). If a feature or concept is difficult to describe clearly or concisely, consider using an example or [image](#images) to complement the text. - **Avoid:** Be mindful of the possibility that you might encounter a different result, depending on the specifics of your configuration, so you might want to do some testing first to see what happens. **Prefer:** Run tests to verify that you get the expected result for your configuration. @@ -101,6 +104,31 @@ Use concise, direct language. Cut unnecessary words unless a conversational tone - **Avoid:** `table_name`: This parameter is used to specify the name of the table you want to modify. **Prefer:** `table_name`: The name of the table to modify. +Avoid these common filler phrases and inflated verbs: + +- **Avoid:** "in order to" + **Prefer:** "to" +- **Avoid:** "due to the fact that" + **Prefer:** "because" +- **Avoid:** "at this point in time" + **Prefer:** "now" +- **Avoid:** "make use of" + **Prefer:** "use" +- **Avoid:** "is able to" + **Prefer:** "can" +- **Avoid:** "in the event that" + **Prefer:** "if" +- **Avoid:** "prior to" + **Prefer:** "before" +- **Avoid:** "with regard to" + **Prefer:** "about" +- **Avoid:** "leverage" + **Prefer:** "use" +- **Avoid:** "utilize" + **Prefer:** "use" +- **Avoid:** "perform" + **Prefer:** a more specific verb, such as "run", "complete", or "execute" + Provide guidance rather than leave decisions to the user. For example, phrases like "change what you need" or "modify the relevant settings" may raise questions like "What would I need to change?" and "Which settings are relevant?". When user discretion is required, be as explicit as possible to reduce ambiguity and cognitive load. - **Avoid:** Increase the threshold as needed. @@ -140,6 +168,28 @@ Do not use language that could be read as presumptuous or condescending. - **Avoid:** Monitoring the cluster is simple. **Prefer:** Monitor the cluster with the following tools: +### Tense + +Use present tense to describe CockroachDB's behavior, the state of the system, and the results of user actions. + +- **Avoid:** When you run the command, CockroachDB will create a new table and will return a confirmation. + **Prefer:** When you run the command, CockroachDB creates a new table and returns a confirmation. +- **Avoid:** The leaseholder will handle all reads and writes for the range. + **Prefer:** The leaseholder handles all reads and writes for the range. + +Use past tense only to refer to something that has already happened within a sequence. + +**Example:** Now that you have created the database, add the schema. + +Use future tense only when referring to something that occurs later in a sequence of steps. + +**Example:** Later in this task, you will create a standby cluster. First, create and start the primary cluster: + +Avoid mixing present and future tense within a single description of system behavior. + +- **Avoid:** CockroachDB assigns a leaseholder to each range, which will handle all reads and writes. + **Prefer:** CockroachDB assigns a leaseholder to each range, which handles all reads and writes. + ### Speculation and feature support Avoid forward-looking language when writing about supported syntax and behavior. Do not suggest that a feature may or may not be added in a future release. Avoid words like "yet" and "currently", and do not reference the internal product roadmap. @@ -153,10 +203,35 @@ For readability, avoid Latinisms. - **Avoid:** Select a deployment option, e.g., {{ site.data.products.standard }} or {{ site.data.products.advanced }}. **Prefer:** Select a deployment option such as {{ site.data.products.standard }} or {{ site.data.products.advanced }}. +- **Avoid:** Because CockroachDB is designed with high fault tolerance, backups are primarily needed for disaster recovery (i.e., if your cluster loses a majority of its nodes). + **Prefer:** Because CockroachDB is designed with high fault tolerance, backups are primarily needed for disaster recovery (that is, if your cluster loses a majority of its nodes). +- **Avoid:** databases, functions, tables, clusters, schemas, rows, users, jobs, etc. + **Prefer:** databases, functions, tables, clusters, schemas, rows, users, jobs, and so on. +- **Avoid:** These can also be queried via `SHOW`. + **Prefer:** These can also be queried using `SHOW`. + +### Modal verbs + +Maintain consistency when using modal verbs to signal the degree of obligation or certainty. + +- Use _must_ to denote a required action with no alternative. Use for prerequisites, security requirements, and hard constraints. +- Use _should_ to denote a recommended action with viable alternatives. Use for best practices and suggestions. +- Use _can_ when describing an action that is possible, but is not directly recommended or not recommended. Use to describe capabilities or options that are available to the user. +- Use _may_ when referencing permissions, or when describing user behavior that is non-deterministic or likely to vary. +- Use _avoid_ to denote actions that we specifically recommend against. Use for practices that are technically possible, but likely to cause difficulty for the user. If possible, include a brief explanation of why the user should avoid the action. +- Use _do not_ only to denote actions that are impossible or will certainly harm the user's system. If there could conceivably be a valid reason for a user to do the action, use "avoid" instead. + +Do not use "should" as a softer form of "must." If the user has no real alternative, use "must." +- **Avoid**: You should enable admission control before running a high-throughput workload. + **Prefer**: You must enable admission control before running a high-throughput workload. + +Do not use "may" when "can" is more accurate. Use "may" only when the behavior or permission genuinely varies. +- **Avoid**: Users may query this table to view active sessions. + **Prefer**: Users can query this table to view active sessions. ## Word usage guidelines -This section logs decisions about dictionary words to use and avoid. Add specific guidelines we decide as a team to this section. Refer also to [Technical terminology](#technical-terminology) for technical terms that may not be in a dictionary. +This section logs decisions about dictionary words to use and avoid. Add specific guidelines we decide as a team to this section. ### CockroachDB products @@ -237,6 +312,14 @@ This is a request from Cockroach Labs' legal team. The idea is to remind the rea Use inclusive language that reflects a diverse readership. Avoid terms that inherently exclude, stereotype, or cause confusion. +### Avoid minimizing language + +Minimizing language implies that a task is easy or obvious, which may not be true for all users. + +Minimizing language includes words like "simple/simply", "just", "easy/easily", "actually", "obviously", "clearly", "of course", "straightforward", "trivial", and more. + +Also avoid the phrases "Note that..." or "Keep in mind that...". If something is worth noting, state it directly. + ### Avoid ableist language An informal tone can allow for problematic ableist language due to figures of speech and colloquial language. Ableist language includes words like "crazy", "insane", "blind", "dummy", "cripple", and more. @@ -283,7 +366,7 @@ Avoid terms that imply violence or harm. - Replace "performance _hit_" with **reduced performance**. - Replace "want to _hit_ up" with **want to visit**. -Terminology around "kill" vs. "stop" vs. "terminate" is nuanced, as described [in this GitHub comment](https://github.com/cockroachdb/docs/issues/7767#issuecomment-662028864). Use your best judgement. +Terminology around "kill" vs. "stop" vs. "terminate" is nuanced. In general, use "terminate" unless referring to a specific command that uses a different term in its syntax. ### Write accessible documentation @@ -299,7 +382,7 @@ Avoid using socially-charged terms for features and technical concepts. **Examples:** - Replace _blacklist / whitelist_ with **denylist / allowlist**. -- Replace _master / slave_ with **main/principal/primary/manager** and **secondary/subordinate/worker**. +- Replace _master_ with **main/principal/primary/manager** and _slave_ with **secondary/subordinate/worker**. - Replace _native_ with **core, built-in, top-level, integrated, "built for"** or omit. - Replace _old_ with **existing, previous, first, original**. @@ -320,7 +403,9 @@ For links to CockroachDB docs, match the capitalization of the linked content: ### Punctuation rules -- Use the [Oxford (aka serial) comma](https://en.wikipedia.org/wiki/Serial_comma). +- Use the Oxford (aka serial) comma. + - **Avoid:** The connection string is pre-populated with your username, password, cluster name and other details. + - **Prefer:** The connection string is pre-populated with your username, password, cluster name, and other details. - Use straight `'` rather than curved `‘` quotes. - Limit semicolon usage. Instead, use two simple sentences. - **Avoid:** CockroachDB is a distributed database; it scales horizontally across multiple nodes. @@ -338,12 +423,6 @@ For links to CockroachDB docs, match the capitalization of the linked content: - Place commas and periods inside quotation marks (for example, `CockroachDB's availability model is described as "Multi-Active Availability."`). Place other punctuation outside quotation marks (for example, `What is "Multi-Active Availability"?`). When any type of punctuation is part of a quote, place it inside the quotation marks (for example, `To phrase it in the form of a question: "Who are the top 10 users by number of rides on a given date?"`). - Avoid using slashes "/" and ampersands "&" in place of "or" and "and" respectively, unless space is very limited (such as in a table). Similarly, avoid using "and/or" unless space is very limited. Instead, decide whether "and" or "or" can stand alone, or make use of "both" when the inclusivity must be explicit (for example, `x or y or both`). -## Vale - -The CockroachDB documentation uses [Vale](https://vale.sh/) to identify common spelling mistakes or other patterns that may contradict the guidelines in this style guide. Check for items flagged by Vale in the **Files Changed** and **Checks** tabs of the pull request, grouped by file. - -Try to address as many of the suggestions as possible. If Vale flags a word that is spelled and used correctly, add the word to `netlify/vale/vocab.txt` in the PR where the word is introduced. For other failed tests, you can work with your reviewer to correct the error in your PR or to improve the Vale test. - ## File conventions File names in the CockroachDB docs repo should be lowercase with a dash between words. File names for docs pages should match the page title whenever possible. @@ -385,8 +464,9 @@ For templates that provide a starting point for writing concept topics, refer to A _task_ topic provides step-by-step instructions to complete a specific goal. Tasks are discrete and action-based. Tasks have the following properties: - Answers the question "how do I do \?" by describing precisely what to do and the order in which to do it. +- The first sentence of a task describes the outcome or goal of the task and directs the reader to the steps that follow. - Corresponds to a specific user journey as defined by Product. -- The title or heading should state an actionable goal for the user, ideally of the form **\ [\|\] \ or \**. +- The title or heading states an actionable goal for the user, ideally of the form **\ [\|\] \ or \**. **Example:** Create an Index @@ -415,6 +495,8 @@ For templates that provide a starting point for writing task topics, refer to th _Reference_ topics provide information about a specific CockroachDB function, feature, or interface. Reference topics are detail-oriented, and should include all of the information available on a specific topic, without providing prescriptive guidance. Prescriptive guidance is reserved for [Guide](#guide) topics. +The first paragraph of a reference topic describes the focus of the information to follow, and briefly clarifies how the information is useful. + Reference topics typically document programming constructs, interface parameters, or facts about a product, but do not provide explanations of [concepts](#concept) or [tasks](#task). Reference topics help users understand the precise meaning and effect of CockroachDB SQL language constructs, platforms, configuration options, API parameter values, etc. @@ -477,6 +559,24 @@ When you use multiple code blocks to demonstrate a task, interleave the code blo ~~~ ``` +Always introduce a code block with a lead-in sentence that ends with a colon. Do not drop a code block into a page without context, even if the preceding heading seems self-explanatory. Make the lead-in sentence as specific as possible. Avoid generic openers like "Run the following command:" when a more descriptive alternative is available. + +- **Avoid:** Run the following command: + **Prefer:** To start a CockroachDB node, run: + **Prefer:** To view the list of active sessions, run the following SQL query: + +When showing the output of a command, introduce it with one of the following consistent phrases: +- "The output looks like:" for representative example output. +- "The command returns:" for exact return values. +- "The output includes:" when the example shows a relevant excerpt, not the full output. + +When a task involves several steps, each with its own code block, give every code block its own lead-in sentence. Do not group multiple steps under a single introduction. + +- **Avoid:** Run the following commands to initialize the cluster and add a user: {two code blocks} + **Prefer:** + - Initialize the cluster: {code block} + - Add a user: {code block} + #### Placeholders Code samples often include placeholder values, to be replaced by values specific to a user's environment. To denote that a value in a code sample is a placeholder value that should be replaced, use curly brackets (`{}`). @@ -514,8 +614,9 @@ CockroachDB docs use three classes of "callouts," which are highlighted blocks o **Best practices:** -- Avoid placing callouts next to each other. -- Do not overuse callouts. Most documentation belongs in the body of a page rather than in a callout. +- Avoid using consecutive callouts. +- Avoid using more than one callout per major section. +- Most documentation belongs in the body of a page rather than in a callout. Only use a callout if including the information in the body would severely disrupt the flow of the writing, or if the information is crucial enough to require special attention. For code block syntax and formatting, refer to the [Markdown Guide](MarkdownGuide.md#callouts). From c6a1b615a1fd70e9a1b93fd0231536152b71e5eb Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Tue, 19 May 2026 16:58:44 -0400 Subject: [PATCH 2/6] more styleguide improvements --- StyleGuide.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/StyleGuide.md b/StyleGuide.md index d4b49f1627c..ceadaf92e98 100644 --- a/StyleGuide.md +++ b/StyleGuide.md @@ -679,6 +679,18 @@ When linking to third-party documentation, consider the purpose and maintenance For link syntax, refer to the [Markdown Guide](MarkdownGuide.md#links). +### UI elements + +Use consistent verbs when describing interactions with UI elements. Do not mix synonyms for the same type of interaction. + +- For activating a button, use _click_. **Example:** Click **Submit**. +- For choosing from a menu, list, or dropdown, use _select_. **Example:** Select **Advanced** from the deployment type menu. +- For pressing a physical button or key, use _press_. **Example:** Press **Enter**. +- For typing into a field, use _enter_. **Example:** In the **Cluster name** field, enter a name for your cluster. +- For enabling or disabling a toggle, use _turn on/off_. **Example:** Turn on **Admission control**. +- For checking or unchecking a checkbox, use _select/deselect_. **Example:** Select the **Enable backups** checkbox. +- For navigating to a page in the UI, use _go to_. **Example:** Go to the **Clusters** page. + ## Page sections For page headings, refer to the [Markdown Guide](MarkdownGuide.md#page-headings). From 071667142c0ca37320d04b2f5dc22e1b9e9cb5ba Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Thu, 21 May 2026 14:25:41 -0400 Subject: [PATCH 3/6] more style guide improvements --- StyleGuide.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/StyleGuide.md b/StyleGuide.md index ceadaf92e98..34f68627c69 100644 --- a/StyleGuide.md +++ b/StyleGuide.md @@ -84,6 +84,23 @@ Do not use "we" to refer to "CockroachDB" or "Cockroach Labs". - **Avoid:** We recommend ... **Prefer:** Cockroach Labs recommends ... +### Anthropomorphization + +CockroachDB can be the grammatical subject of an active-voice sentence describing its behavior. However, when using CockroachDB as the subject, do not use verbs that imply human cognition or emotion. + +Avoid verbs that suggest awareness or intent: "knows", "wants", "decides", "thinks", "believes", "understands", "sees", "prefers", "chooses", "expects". + +Instead, describe the actual mechanical or computational action: "assigns", "returns", "determines", "creates", "stores", "checks", "validates", "rejects", "routes", "distributes", "replicates", "calculates", "records", "tracks". + +- **Avoid**: CockroachDB knows which node owns the range. + **Prefer**: CockroachDB tracks which node holds the lease for each range. + +- **Avoid**: CockroachDB decides where to place replicas based on locality constraints. + **Prefer**: CockroachDB distributes replicas according to your locality constraints. + +- **Avoid**: CockroachDB understands that the cluster is under high load. + **Prefer**: CockroachDB detects high load and adjusts admission control accordingly. + ### Prescriptive writing Write in a prescriptive style that clearly guides the user. The user should feel confident and supported, without having to infer meaning or make too many decisions on their own. @@ -108,24 +125,34 @@ Avoid these common filler phrases and inflated verbs: - **Avoid:** "in order to" **Prefer:** "to" + - **Avoid:** "due to the fact that" **Prefer:** "because" + - **Avoid:** "at this point in time" **Prefer:** "now" + - **Avoid:** "make use of" **Prefer:** "use" + - **Avoid:** "is able to" **Prefer:** "can" + - **Avoid:** "in the event that" **Prefer:** "if" + - **Avoid:** "prior to" **Prefer:** "before" + - **Avoid:** "with regard to" **Prefer:** "about" + - **Avoid:** "leverage" **Prefer:** "use" + - **Avoid:** "utilize" **Prefer:** "use" + - **Avoid:** "perform" **Prefer:** a more specific verb, such as "run", "complete", or "execute" @@ -174,6 +201,7 @@ Use present tense to describe CockroachDB's behavior, the state of the system, a - **Avoid:** When you run the command, CockroachDB will create a new table and will return a confirmation. **Prefer:** When you run the command, CockroachDB creates a new table and returns a confirmation. + - **Avoid:** The leaseholder will handle all reads and writes for the range. **Prefer:** The leaseholder handles all reads and writes for the range. @@ -203,10 +231,13 @@ For readability, avoid Latinisms. - **Avoid:** Select a deployment option, e.g., {{ site.data.products.standard }} or {{ site.data.products.advanced }}. **Prefer:** Select a deployment option such as {{ site.data.products.standard }} or {{ site.data.products.advanced }}. + - **Avoid:** Because CockroachDB is designed with high fault tolerance, backups are primarily needed for disaster recovery (i.e., if your cluster loses a majority of its nodes). **Prefer:** Because CockroachDB is designed with high fault tolerance, backups are primarily needed for disaster recovery (that is, if your cluster loses a majority of its nodes). + - **Avoid:** databases, functions, tables, clusters, schemas, rows, users, jobs, etc. **Prefer:** databases, functions, tables, clusters, schemas, rows, users, jobs, and so on. + - **Avoid:** These can also be queried via `SHOW`. **Prefer:** These can also be queried using `SHOW`. @@ -229,6 +260,43 @@ Do not use "may" when "can" is more accurate. Use "may" only when the behavior o - **Avoid**: Users may query this table to view active sessions. **Prefer**: Users can query this table to view active sessions. +### Transition and connective language + +Transitions help readers follow the relationship between ideas, but overused or redundant transitions add length without adding clarity. Avoid these commonly overused transitions: + +- "Note that...": State the information directly. Consider whether emphasizing the information is important enough to use a [note callout](#callouts). +- "As mentioned above" / "As noted earlier" / "As previously described": Either briefly restate the information or link to the relevant section. Do not ask the reader to remember something from earlier in the page. +- "Furthermore," "Moreover," "Additionally" at the start of a sentence: These transitions are usually redundant. If ideas are related, their connection should be clear from context. +- "However" / "But" at the start of a sentence: Use sparingly. When contrast is implied by the surrounding content, omit the transition. + +Use parallel structure withing lists and sequences. When items in a list or steps in a sequence share the same grammatical form, they are easier to scan. Begin each item with the same part of speech, ideally a verb. + +- **Avoid:** + - Create a cluster. + - The database should then be configured. + - Running the migration script completes the setup. + **Prefer:** + - Create a cluster. + - Configure the database. + - Run the migration script. + +### Conditional and variable behavior + +When giving conditional instructions, lead with the condition, not the result. This tells the user whether a step applies to them before they read what to do. + +- **Avoid:** Run `cockroach start` after verifying that the node is healthy. + **Prefer:** After verifying that the node is healthy, run `cockroach start`. + +When dealing with variable behavior, be specific. Do not use vague qualifiers like "depending on your setup," "this may vary," or "results may differ" without explaining exactly what behavior varies. + +- **Avoid:** The default value may vary depending on your configuration. + **Prefer:** The default value is X for CockroachDB Basic clusters and Y for CockroachDB Advanced clusters. + +Do not use "depending on your use case" as a standalone qualifier. If a choice depends on the use case, describe the use cases and their corresponding recommendations. + +- **Avoid:** You may want to adjust this setting depending on your use case. + **Prefer:** Increase this value if your workload involves frequent long-running transactions. Keep the default if your workload is primarily short reads and writes. + ## Word usage guidelines This section logs decisions about dictionary words to use and avoid. Add specific guidelines we decide as a team to this section. @@ -423,6 +491,30 @@ For links to CockroachDB docs, match the capitalization of the linked content: - Place commas and periods inside quotation marks (for example, `CockroachDB's availability model is described as "Multi-Active Availability."`). Place other punctuation outside quotation marks (for example, `What is "Multi-Active Availability"?`). When any type of punctuation is part of a quote, place it inside the quotation marks (for example, `To phrase it in the form of a question: "Who are the top 10 users by number of rides on a given date?"`). - Avoid using slashes "/" and ampersands "&" in place of "or" and "and" respectively, unless space is very limited (such as in a table). Similarly, avoid using "and/or" unless space is very limited. Instead, decide whether "and" or "or" can stand alone, or make use of "both" when the inclusivity must be explicit (for example, `x or y or both`). +### Numbers and measurements + +The following rules apply only to your own writing. When representing example commands, outputs, or UI elements, always use the exact wording that the user sees in practice. + +In prose, spell out whole numbers one through nine. Use numerals for 10 and above. + +- **Example:** There are three replicas by default. +- **Example:** A cluster with 10 or more nodes benefits from zone-level fault tolerance. + +In technical contexts, always use numerals regardless of size. This includes: + +- Measurements with units: "5 minutes," "128 MiB," "3 seconds" +- SQL values and parameters: LIMIT 5, max_offset = 500ms +- Percentages: "5%" (not "five percent") +- Version numbers: v25.1 + +For units, use the following conventions: + +- Use "GiB" and "MiB" (not "GB" and "MB") for binary storage values, consistent with the DB Console and CockroachDB output. +- In prose, write time durations with the unit spelled out: "5 minutes," "30 seconds." Do not abbreviate time units in prose ("5 min," "30s"). +- Place a numeral directly before the unit with a space between them: "3 nodes," "128 MiB," "5 minutes." + +Express numerical ranges with "to" between values: "3 to 5 nodes." This is consistent with the version range convention (`v22.1.0` to `v22.1.4`). Do not use dashes for ranges. + ## File conventions File names in the CockroachDB docs repo should be lowercase with a dash between words. File names for docs pages should match the page title whenever possible. From 004356f171e6d241780641745e6cafd98c2ab6cb Mon Sep 17 00:00:00 2001 From: Peach Leach <87079419+peachdawnleach@users.noreply.github.com> Date: Tue, 26 May 2026 16:33:46 -0400 Subject: [PATCH 4/6] Update StyleGuide.md Co-authored-by: Ryan Kuo <8740013+taroface@users.noreply.github.com> --- StyleGuide.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/StyleGuide.md b/StyleGuide.md index 34f68627c69..4d127f23dce 100644 --- a/StyleGuide.md +++ b/StyleGuide.md @@ -262,7 +262,9 @@ Do not use "may" when "can" is more accurate. Use "may" only when the behavior o ### Transition and connective language -Transitions help readers follow the relationship between ideas, but overused or redundant transitions add length without adding clarity. Avoid these commonly overused transitions: +Transitions help readers follow the relationship between ideas, but overused or redundant transitions add length without adding clarity. + +Avoid these commonly overused transitions: - "Note that...": State the information directly. Consider whether emphasizing the information is important enough to use a [note callout](#callouts). - "As mentioned above" / "As noted earlier" / "As previously described": Either briefly restate the information or link to the relevant section. Do not ask the reader to remember something from earlier in the page. From 56c34976924c3325e0f20c9ac4c4bf85ad871076 Mon Sep 17 00:00:00 2001 From: Peach Leach <87079419+peachdawnleach@users.noreply.github.com> Date: Tue, 26 May 2026 16:34:29 -0400 Subject: [PATCH 5/6] Update StyleGuide.md Co-authored-by: Ryan Kuo <8740013+taroface@users.noreply.github.com> --- StyleGuide.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/StyleGuide.md b/StyleGuide.md index 4d127f23dce..9f2e99c9028 100644 --- a/StyleGuide.md +++ b/StyleGuide.md @@ -277,7 +277,8 @@ Use parallel structure withing lists and sequences. When items in a list or step - Create a cluster. - The database should then be configured. - Running the migration script completes the setup. - **Prefer:** + +**Prefer:** - Create a cluster. - Configure the database. - Run the migration script. From 73b1be88437241e9aa113c0b3ecb328a8c33408f Mon Sep 17 00:00:00 2001 From: Peach Leach <87079419+peachdawnleach@users.noreply.github.com> Date: Tue, 26 May 2026 16:39:33 -0400 Subject: [PATCH 6/6] Update StyleGuide.md Co-authored-by: Ryan Kuo <8740013+taroface@users.noreply.github.com> --- StyleGuide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/StyleGuide.md b/StyleGuide.md index 9f2e99c9028..7fd271fa980 100644 --- a/StyleGuide.md +++ b/StyleGuide.md @@ -506,7 +506,7 @@ In prose, spell out whole numbers one through nine. Use numerals for 10 and abov In technical contexts, always use numerals regardless of size. This includes: - Measurements with units: "5 minutes," "128 MiB," "3 seconds" -- SQL values and parameters: LIMIT 5, max_offset = 500ms +- SQL values and parameters: `LIMIT 5`, `max_offset = 500ms` - Percentages: "5%" (not "five percent") - Version numbers: v25.1