From dde17c05fb3931836bfe0d3d522202bb6a2e1433 Mon Sep 17 00:00:00 2001 From: Ryan Kuo Date: Fri, 5 Sep 2025 12:58:37 -0400 Subject: [PATCH 1/4] full pass on Style Guide --- MarkdownGuide.md | 55 ++--- StyleGuide.md | 525 +++++++++++++++++++++++++++-------------------- 2 files changed, 326 insertions(+), 254 deletions(-) diff --git a/MarkdownGuide.md b/MarkdownGuide.md index 5bb8710c111..73ae06e2aef 100644 --- a/MarkdownGuide.md +++ b/MarkdownGuide.md @@ -149,7 +149,7 @@ For websites that automatically localize pages, avoid using localization element ### Inline code -Use inline code when referring to code, commands, or other technical syntax within a sentence. Inline `code` is surrounded by backticks (``). +Use inline code when referring to code, commands, values, or other technical syntax within a sentence. Inline `code` is surrounded by backticks (``). **Example:** The `CREATE TABLE` statement creates a new table in a database. @@ -213,23 +213,6 @@ Notes for usage: - **Copy to Clipboard** should be used for every code block that can be **executed**. - To render properly, there must be a line break above the `{% include_cached copy-clipboard.html %}` line. -### 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 (`{}`). - -For example: `SELECT * FROM TABLE {mytable};`. In this code sample, `{mytable}` would be replaced by some table name before the code could actually run. - -When you use placeholders, you usually need to define the value within the brackets, if the placeholder value isn't clear. Define placeholder values immediately following the code sample: - -- For a single placeholder value, use a follow-up sentence. -- For multiple placeholder values, use a bulleted list. -- For many placeholder values (10+), use a table. -- For large code blocks, define the placeholder values inside the code block with an inline code comment. - -Ensure that placeholders are placed within backticks: `SET {session variable}`. This signifies that placeholder values are code. - -If the code sample is sensitive to curly bracket characters (e.g., JavaScript), you can use `<>` instead. - ### Escaping special characters Sometimes you may need to escape special characters to achieve proper rendering: @@ -396,6 +379,34 @@ You can use the following HTML formatting within an HTML table: - Use HTML only when Markdown doesn't provide the necessary functionality. - When mixing Markdown and HTML, ensure proper spacing and formatting. Preview the rendered page locally. +## Callouts + +CockroachDB docs use three classes of "callouts," which are highlighted blocks of text: tips, notes, and warnings. + +- To insert a **tip**, use the following code: + + ~~~ + {{site.data.alerts.callout_success}} + tip text goes here + {{site.data.alerts.end}} + ~~~ + +- To insert a **note**, use the following code: + + ~~~ + {{site.data.alerts.callout_info}} + note text goes here + {{site.data.alerts.end}} + ~~~ + +- To insert a **warning**, use the following code: + + ~~~ + {{site.data.alerts.callout_danger}} + warning text goes here + {{site.data.alerts.end}} + ~~~ + ## Images Use the following HTML and Liquid to include an image in a Markdown page: @@ -476,14 +487,6 @@ A patch release version of CockroachDB receives updates as patches. To refer to ## Include files -Sometimes content needs to be duplicated across two or more pages in the documentation. For example, there may be several pages that need the same cluster setup, but describe how to use different features. Or a very specific [note](#notes) or [warning](#warnings) needs to be added to several different pages. - -In these situations, you will need to use an _include file_. An include file is a separate Markdown file (stored in `_includes/some/shared-file.md`) where you will write content that is shared across multiple pages. - -For more information about include files, see [the Jekyll `include` documentation](https://jekyllrb.com/docs/includes/). - -_Note_: Using include files adds complexity to the docs site architecture and build process. It also makes writing the documentation more tricky, because instead of working on text in one document, the writer has to jump between two or more files. If you can link to existing content rather than using an include file, strongly consider doing that instead. - There are [basic](#basic-include-file-usage) and [advanced](#advanced-include-file-usage) methods for using include files. Use the basic method unless you are sure you need the advanced. diff --git a/StyleGuide.md b/StyleGuide.md index ed5f90d1659..3cfe03c51f7 100644 --- a/StyleGuide.md +++ b/StyleGuide.md @@ -5,98 +5,219 @@ The following guidance is provided to benefit CockroachDB docs authors and revie Included in this guide: - [Style and tone](#style-and-tone) -- [Inclusive language](#inclusive-language) + - [Perspective and voice](#perspective-and-voice) + - [Prescriptive writing](#prescriptive-writing) + - [Speculation and feature support](#speculation-and-feature-support) + - [Latinisms](#latinisms) +- [Word usage guidelines](#word-usage-guidelines) + - [CockroachDB products](#cockroachdb-products) + - [CockroachDB versions](#cockroachdb-versions) + - [Third-party products](#third-party-products) +- [Inclusivity](#inclusivity) - [Avoid ableist language](#avoid-ableist-language) - - [Examples](#examples) - [Avoid unnecessarily gendered language](#avoid-unnecessarily-gendered-language) - - [Examples](#examples-1) - [Write diverse and inclusive examples](#write-diverse-and-inclusive-examples) - [Avoid unnecessarily violent language](#avoid-unnecessarily-violent-language) - - [Examples](#examples-2) - [Write accessible documentation](#write-accessible-documentation) - [Write about features and users in inclusive ways](#write-about-features-and-users-in-inclusive-ways) - - [Examples](#examples-3) - [Capitalization and punctuation](#capitalization-and-punctuation) - [Capitalization rules](#capitalization-rules) - [Punctuation rules](#punctuation-rules) - [Vale](#vale) - [File conventions](#file-conventions) - - [Examples](#examples-4) - - [File naming](#file-naming) -- [Product names](#product-names) - [Page components](#page-components) - - [GitHub issues and pull requests](#github-issues-and-pull-requests) - - [Tips, notes, and warnings](#tips-notes-and-warnings) - - [Tips](#tips) - - [Notes](#notes) - - [Warnings](#warnings) - - [CockroachDB version callout](#cockroachdb-version-callout) - - [Known limitations](#known-limitations) - - [What are known limitations?](#what-are-known-limitations) - - [Where to find known limitations](#where-to-find-known-limitations) - - [When to document known limitations](#when-to-document-known-limitations) - - [Who documents known limitations](#who-documents-known-limitations) - - [Where to document known limitations](#where-to-document-known-limitations) - - [How to document known limitations](#how-to-document-known-limitations) - - [Examples](#examples-15) -- [Content elements](#content-elements) + - [Code](#code) + - [Callouts](#callouts) - [Images](#images) - [Videos](#videos) -- [Word usage guidelines](#word-usage-guidelines) + - [Include files](#include-files) + - [GitHub links](#github-links) + - [Known limitations](#known-limitations) For Markdown-specific syntax and formatting guidelines, refer to the [Markdown Guide](MarkdownGuide.md). ## Style and tone -CockroachDB docs should be helpful, humble, positive, and friendly. To achieve this, all docs should be factual and free from hyperbolic language. +CockroachDB docs should be helpful, humble, positive, friendly, and free from hyperbolic language. + +### 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. + +**Examples:** + +- Run `cockroach start`. +- Click **Next**. + +In tutorials, where a conversational tone is sometimes helpful, use the second person ("you"). + +**Examples:** + +- In this tutorial, you'll start with a new cluster, so stop and clean up any existing clusters. +- After you create the database, insert some rows. + +In page titles and headings, use the imperative mood to name a task. Do not use the gerund form or a noun phrase. + +- **Avoid:** Managing Users + **Avoid:** User Management + **Prefer:** Manage Users + +Do not use "we" to refer to "CockroachDB" or "Cockroach Labs". + +- **Avoid:** We support changefeeds. + **Prefer:** CockroachDB supports changefeeds. + +- **Avoid:** We recommend ... + **Prefer:** Cockroach Labs recommends ... -Other general guidance about language and tone: +### Prescriptive writing -- For [reference and general task-based docs](#reference-and-task-based-docs), use the second-person imperative present tense, also known as the "[imperative mood](https://www.grammar-monster.com/glossary/imperative_mood.htm)." These docs should be straightforward and conventional. +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. - **Example:** In a new terminal, as the `root` user, use the `cockroach user` command to create a new user, `maxroach`. +Use active instead of passive voice. - **Example:** Now that you have a database, user, and a table, run the following code to insert rows into the table. +- **Avoid:** Each parameter should be set explicitly. + **Prefer:** Set each parameter explicitly. -- Recommended usage of the personal pronoun "we": +- **Avoid:** Additional options can be specified. + **Prefer:** You can specify additional options. - - "We" can be used to describe the group of people developing CockroachDB, instead of "Cockroach Labs," only when it is clear who "we" is referring to. - - Do not use "we" in place of "CockroachDB" for when you are talking about something the _product_ does or supports. - - Do not use "we" in tutorials. See the next bullet for more on tutorials and examples. +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. -- For tutorials and examples, we recommend you use the second-person point of view (e.g., you). These docs should be more casual and conversational, as if they are teaching the user, but still straightforward and clear. +- **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. - **Example:** In this lab, you'll start with a fresh cluster, so make sure you've stopped and cleaned up the cluster from the previous labs. +- **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. -- Use active voice instead of passive. For more information, refer to the [Purdue Online Writing Lab resource](https://owl.english.purdue.edu/owl/resource/539/02/). -- Use simple and direct language. Grammar can be incorrect to save simplicity (e.g., many descriptions in reference docs are phrases). +Provide guidance rather than leave decisions to the user. Avoid vague phrases like "as you wish" or "of your choice". When user discretion is required, be as explicit as possible to reduce ambiguity and cognitive load. - **Example:** `table name`: The name of the table to create audit logs for. +- **Avoid:** Increase the threshold as needed. + **Prefer:** Increase the threshold until you see a performance improvement. -- Avoid using "please" when giving an instruction, except when asking the user to go outside the scope of the task (such as contacting Cockroach Labs or filing a support issue). +- **Avoid:** Define additional settings as desired. + **Prefer:** You can define additional settings in the configuration file. To change the default host and port, set `host` and `port` respectively. To change the path, ... -- To expand upon the idea of "free from hyperbolic language", avoid the use of the word "simple" (along with "just", "easily", "actually", etc.) since it's not really possible to tell what might be easy or hard for the user. Something you think is simple may be challenging for them. +- **Avoid:** Edit the profile using your preferred text editor. + **Prefer:** Edit the profile in a text editor. -- Use contractions to simplify language, but not in cases where a clear directive or prohibition is being given (e.g., `do not` / `cannot` / `should not` instead of `don't` / `can't` / `shouldn't`). +Avoid vague time estimates. Provide a specific timeframe when possible. - **Example:** You cannot change primary key using `ALTER TABLE`. +- **Avoid:** You should set the grace period to at least a few minutes. + **Prefer:** Set the grace period to at least 5 minutes. - **Example:** If you leave versioned binaries on your servers, you do not need to do anything. +- **Avoid:** This should take a few moments. When finished, click **Next**. + **Prefer:** When finished, click **Next**. + +Do not use contractions when giving a technical description or instruction. + +- **Example:** You cannot change primary key using `ALTER TABLE`. +- **Example:** If you leave versioned binaries on your servers, you do not need to do anything. + +Do not use "please" when giving an instruction, except when asking the user to go outside the scope of the task (for example, contacting Cockroach Labs or filing a support issue). + +- **Example:** If you need assistance, please contact [support](https://support.cockroachlabs.com/). + +- **Avoid:** Please click on the **Next** button. + **Prefer:** Click **Next**. + +Do not use language that could be read as presumptuous or condescending. + +- **Avoid:** If you aren't willing to do this for some reason, ... + **Prefer:** If this is not possible, ... + +- **Avoid:** Monitoring the cluster is simple. + **Prefer:** Monitor the cluster with the following tools: + +### 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. + +- **Avoid:** CockroachDB does not yet support column-level privileges. This is planned for a future release. + **Prefer:** CockroachDB does not support column-level privileges. + +### Latinisms + +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 }}. + +## Word usage guidelines -- Avoid using 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. - - Do not use the words "yet" and "currently" when writing about a feature that we do or do not support. - - Do not reference the internal product roadmap. +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. -## Inclusive language +### CockroachDB products -We want our education materials to be inclusive and written with diversity in mind. This section provides general guidelines, best practices, and examples when writing docs or training materials. This is a work in progress and we welcome any feedback and additions. +- Use the following combinations of `CockroachDB` and Liquid variables to display product names on docs pages. Liquid variables cannot be used in Markdown front-matter, file names, or non-Markdown files. In those cases, write the product names manually. + + - **CockroachDB Cloud** : `CockroachDB {{ site.data.products.cloud }}` + - **CockroachDB Basic** : `CockroachDB {{ site.data.products.basic }}` + - **CockroachDB Standard** : `CockroachDB {{ site.data.products.standard }}` + - **CockroachDB Advanced** : `CockroachDB {{ site.data.products.advanced }}` + - **CockroachDB self-hosted cluster** : `CockroachDB {{ site.data.products.core }} cluster` + +- Use the full product name on its first occurrence on a page. You may subsequently shorten product names to "Basic", "Advanced", or "Cloud", unless this would introduce ambiguity (for example, on long pages where product names might be separated by multiple paragraphs). + +- Do not shorten "CockroachDB" to "CRDB". + +- Use "`cockroach`" to refer to the CockroachDB binary. + + - **Avoid:** Cockroach process + **Prefer:** `cockroach` process + +### CockroachDB versions + +Refer to CockroachDB versions as `vxx.x.x` (for example, `v21.1.8`). Do not use `version xx.x.x`. + +For version ranges, use `to` between numbers (for example, `v22.1.0 to v22.1.4`). Do not use a dash. Refer to [Punctuation rules](#punctuation-rules). + +Refer to "earlier" and "later" versions, rather than "lower" and "higher" versions. For example, `CockroachDB v25.3 and earlier`. + +### Third-party products + +In general, align third-party branding with that brand's usage. Do not use the shortened versions of product names. + +| Avoid | Prefer | +|----------|------------| +| Postgres | PostgreSQL | +| K8s | Kubernetes | + +### "Directory" vs. "folder" + +- Use "directory" to refer to a filesystem directory, either locally or in a VM. For example, `Compress the directory into a .zip archive.` +- Use "folder" to refer to a folder within a UI, such as a web UI or an IDE. For example, `Create a folder in your CockroachDB Cloud organization.` + +### "Legacy" vs. "deprecated" + +- Use "legacy" only for our own earlier products, features, or workflows to signal that a newer option is preferred. Avoid using "legacy" as a pejorative; if no preference is intended, say "earlier" or "previous". Do not use "legacy" to refer to competitors' products. +- Prefer "deprecated" when there is an approved plan for end of support and removal. If deprecation is not approved but guidance is needed, you may call the previous option "legacy". + +### "In" vs. "on" a cluster + +Use "in a cluster" when referring to elements that form the cluster itself. + +**Examples:** + +- Nodes in the cluster +- Ranges in the cluster + +Use **on a cluster** when referring to workloads, services, or databases that run on the cluster's infrastructure. + +**Examples:** + +- Databases on the cluster +- Jobs running on the cluster + +## Inclusivity + +Use inclusive language that reflects a diverse readership. Avoid terms that inherently exclude, stereotype, or cause confusion. ### 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. -#### Examples +**Examples:** - Replace _dummy_ with **placeholder, sample**. - Replace _sanity-check_ with **final check, confirm**. @@ -105,13 +226,12 @@ An informal tone can allow for problematic ableist language due to figures of sp Be aware of personal pronouns in examples and outdated gendered terms. -Best practices: +**Best practices:** - Avoid personal pronouns (i.e., use proper nouns, "the user", etc.). - If a personal pronoun is needed for clarity or conciseness, default to gender-neutral pronouns (they/them). -- Be aware of other possible gendered language (e.g., man-hours, man-in-the-middle attacks), and find alternatives. -#### Examples +**Examples:** - Replace _man hours_ with one of: **work hours**, **staff hours**, **person hours**. - Replace _manning_ with **staffing**. @@ -119,20 +239,20 @@ Best practices: ### Write diverse and inclusive examples -Avoid examples that are US-specific or centric. +Avoid examples that are U.S.-specific or centric. -Best practices: +**Best practices:** -- Avoid US-specific holidays, sports, figures of speech, etc. +- Avoid U.S.-specific holidays, sports, figures of speech, etc. - Use a diverse set of names in examples. ### Avoid unnecessarily violent language -Avoid violent or harmful terms. +Avoid terms that imply violence or harm. -#### Examples +**Examples:** -- Replace "_kill_" with **terminate** +- Replace "_kill_" with **terminate**. - Replace "_hit_ Enter" with **press Enter**. - Replace "_hit_ your resource limits" with **reach your resource limits** - Replace "_hit_ an error" with **experience an error**. @@ -144,59 +264,55 @@ Terminology around "kill" vs. "stop" vs. "terminate" is nuanced, as described [i ### Write accessible documentation - Don't use directional terms as the only clue to location within a page. "Left", "right", "up", "down", "above", and "below" aren't useful for people who use screen-reading software. Good replacements are "preceding" and "following". If you must use a directional term, provide additional text about the location, such as in the Save As dialog box, on the Standard toolbar, or in the title bar. -- Provide Alt text that adequately summarizes the intent of each image. +- Replace "_see_" with **refer to**. +- Provide [alt text](https://en.wikipedia.org/wiki/Alt_attribute) that adequately summarizes the intent of each [image](#images). - Link text should be the same as or summarize the title of the link target. Avoid **here** and **this documentation**. ### Write about features and users in inclusive ways Avoid using socially-charged terms for features and technical concepts. -#### Examples +**Examples:** -- Replace _blacklist / whitelist_ with **denylist / allowlist** -- Replace _master / slave_ with **main/principal/primary/manager** and **secondary/subordinate/worker** -- Replace _native_ with **core, built-in, top-level, integrated, "built for"** or omit -- Replace _old_ with **existing, previous, first, original** +- Replace _blacklist / whitelist_ with **denylist / allowlist**. +- Replace _master / slave_ with **main/principal/primary/manager** and **secondary/subordinate/worker**. +- Replace _native_ with **core, built-in, top-level, integrated, "built for"** or omit. +- Replace _old_ with **existing, previous, first, original**. ## Capitalization and punctuation ### Capitalization rules -- Use title case for titles. -- Use sentence case instead of title case for all [headings](#headings). -- Capitalize proper nouns, CockroachDB specific terms, and the names of UI features. - - **Examples:** CockroachDB, Cockroach Labs, the Overview dashboard, the SQL Queries graph - -- Follow SQL capitalization standards. -- In body text, only capitalize proper nouns. Do not capitalize common nouns, even if the common noun is an important product concept. - - **Example:** +- Use [title case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case) for titles. +- Use [sentence case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case) for all [headings](#headings). +- Capitalize proper nouns, CockroachDB product terms, and the names of UI features. + - **Examples:** CockroachDB, Cockroach Labs, the Overview dashboard, the SQL Queries graph +- Follow [SQL capitalization standards](https://dataschool.com/how-to-teach-people-sql/syntax-conventions/#all-caps-sql-commands) for SQL syntax. - - Correct: New clusters will now have admission control enabled by default. - - Incorrect: New clusters will now have Admission Control enabled by default. +For links to CockroachDB docs, match the capitalization of the linked content: -#### Link capitalization - -For [links](#links), capitalization should match the context: - -- **Use title case** when referring to the linked doc by its page title (e.g., "See __Best Practices__ for more information"). -- **Use sentence case** when referring to the linked doc by one of its headers (e.g., "See __Clock synchronization__ for further guidance"). -- **Use sentence case** when referring to a linked doc without explicitly citing a page title or header (e.g., "[…] follow the __identifier rules__ when creating […]"). +- Use title case when referring to the linked doc by its page title (for example, `Refer to [Migration Strategy](https://www.cockroachlabs.com/docs/molt/migration-strategy) for more information.`). +- Use sentence case when referring to the linked doc by one of its headers (for example, `Refer to [Capacity planning](https://www.cockroachlabs.com/docs/molt/migration-strategy#capacity-planning) for further guidance.`). ### Punctuation rules -- Limit semicolon usage. Instead, try two simple sentences. -- Don't use end punctuation (e.g., periods or colons) in headings. -- Use periods at the end of list items if they are sentences or complete a sentence. -- Use the [Oxford (a.k.a. serial) comma](https://en.wikipedia.org/wiki/Serial_comma). -- Append singular possessive nouns with `'s`, including when they end with `s`. For example, `Cockroach Labs's`. -- Ensure commas and periods are inside quotation marks, e.g., _CockroachDB's availability model is described as "Multi-Active Availability."_ Place other punctuation outside quotation marks, e.g., _What is "Multi-Active Availability"?_ . When any type of punctuation is part of a quote, place it inside the quotation marks, e.g., _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 `&` as conjunctions in place of **or** and **and** respectively, unless space is very limited (e.g., in a table). -- Avoid using _and/or_ unless space is very limited (e.g., in a table). Instead, decide whether **and** or **or** can stand alone or make use of **both** when the inclusivity must be explicit, e.g., **x or y or both**. +- Use the [Oxford (aka serial) comma](https://en.wikipedia.org/wiki/Serial_comma). +- 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. + **Prefer:** CockroachDB is a distributed database. It scales horizontally across multiple nodes. +- Do not end headings with punctuation (for example, periods or colons). +- Use periods on either all [list items](MarkdownGuide.md#lists) or none. If some items are sentences or complete a sentence, use periods. +- Use colons instead of dashes. + - **Avoid:** **Default** - true + **Prefer:** **Default:** true - When listing a range of versions, do not use a dash. Instead, separate the first and last versions with `to` (for example, `v22.1.0 to v22.1.4`). - -For more detail about how to format text, see [Components](#components). +- For singular proper nouns ending in **s**, form the possessive with **'s**. + - **Example:** Postgres's syntax +- For plural words or names ending in **s**, form the possessive with just an apostrophe. + - **Example:** Cockroach Labs' products +- 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 @@ -206,108 +322,126 @@ Try to address as many of the suggestions as possible. If Vale flags a word that ## File conventions -CockroachDB docs are mainly comprised of pages (`.md`) and images (`.png` or `.gif`). File names are lowercase with a dash between words, and should be brief but descriptive. +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. -### Examples +**Examples:** - `this-is-a-doc.md` - `name-of-your-image.png` -Each version's pages are found in a directory named for the version. For example, pages for CockroachDB v21.1 are in the `docs > v21.1` directory. For more information about page structure, see the [Pages](https://github.com/cockroachdb/docs/blob/main/CONTRIBUTING.md#pages) section in our [Contributing Guide](https://github.com/cockroachdb/docs/blob/main/CONTRIBUTING.md). For more information about how to style page content, see [Components](#components). +## Page components + +This section describes how to approach page elements other than body text. For Markdown-specific syntax and formatting guidelines, refer to the [Markdown Guide](MarkdownGuide.md). -Each version's images are stored in a versioned directory under the `images` directory. For example, images for CockroachDB v21.1 are in the `docs > images > v21.1` directory. For more information, see [Images](#images). +### Code -### File naming +#### Code blocks -File names should match the page title. If you need to change a file name, it is necessary to do the following: +Use separate code blocks for input and output. For example, rather than place both a SQL command and its resulting output within a single code block, place the SQL command inside one code block, followed by its output in another code block. -- Add the previous page URL with the new URL to `_redirects`. -- Replace all links to the previous file name with the new file name in the applicable docs versions. +When you use multiple code blocks to demonstrate a task, interleave the code blocks with text that explains the content of each code block and clarifies where it stands in the overall flow. -## Product names +**Example:** -All product names except CockroachDB should be written as Liquid variables unless part of front-matter, file names, or non-Markdown files. Use the following code in place of product names: +``` +1. To view all virtual clusters on the standby, run: -- **CockroachDB Cloud** : `CockroachDB {{ site.data.products.cloud }}` -- **CockroachDB Basic** : `CockroachDB {{ site.data.products.basic }}` -- **CockroachDB Standard** : `CockroachDB {{ site.data.products.standard }}` -- **CockroachDB Advanced** : `CockroachDB {{ site.data.products.advanced }}` -- **self-hosted** : `CockroachDB {{ site.data.products.core }} cluster` + {% include_cached copy-clipboard.html %} + ~~~ sql + SHOW VIRTUAL CLUSTERS; + ~~~ -The first occurrence of a product name within a docs page should use its full name. At the writer's discretion, subsequent occurrences may be shortened to "Basic", "Advanced", or "Cloud", unless a writer (or reviewer) senses contextual ambiguity that could be improved by using the full product name. In long pages, it may be helpful to use the full name for each occurrence in a new sentence or if it's been a few paragraphs since an occurrence of the full product name. + The standby cluster will show the `main` virtual cluster is in a `replicating` state. -## Page components + ~~~ + id | name | data_state | service_mode + -----+--------+-------------+--------------- + 1 | system | ready | shared + 3 | main | replicating | none + (2 rows) + ~~~ +``` -### GitHub issues and pull requests +#### Placeholders -[Release notes](https://www.cockroachlabs.com/docs/releases/index.html) and [technical advisories](https://www.cockroachlabs.com/docs/advisories/index.html) contain links to individual GitHub issues and pull requests. +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 (`{}`). -Reference issues and pull requests by their corresponding number, prepended with `#`. +- **Example:** `SELECT * FROM TABLE {mytable};`. -**Example:** `[#1](https://github.com/cockroachdb/docs/pull/1)` +When you use placeholders, you usually need to define the value within the brackets, if the placeholder value isn't clear. Define placeholder values immediately following the code sample: -### Tips, notes, and warnings +- For a single placeholder value, use a follow-up sentence. +- For multiple placeholder values, use a bulleted list. +- For many placeholder values (10+), use a table. +- For large code blocks, define the placeholder values inside the code block with an inline code comment. -Our docs use three classes of highlighted text (also referred to as callouts): +Ensure that placeholders are placed within backticks: `SET {session variable}`. This signifies that placeholder values are code. -- [Tips](#tips) -- [Notes](#notes) -- [Warnings](#warnings) +If the code sample is sensitive to curly bracket characters (as in JavaScript), you can use `<>` instead. -The highlighting is generated using Liquid tags, each of which must be on its own line. You can use Markdown (preferred) or HTML within the highlighted text. +### Callouts -#### Tips +CockroachDB docs use three classes of "callouts," which are highlighted blocks of text: tips, notes, and warnings. -Use a tip to highlight nice-to-know pieces of information. +- Use a _tip_ to highlight nice-to-know pieces of information. -For example, you might include a tip to our GitHub repo's Terraform scripts on the Google Cloud Engine deployment page. It's nice to know it's there, but doesn't clarify anything nor is it critical. + For example, you might use a tip to link to our GitHub repo's Terraform scripts on the Google Cloud Engine deployment page. It's nice to know it's there, but doesn't clarify anything nor is it critical. -To insert a tip, use the following code: +- Use a _note_ to call attention to a piece of clarifying information. This information should **not** be crucial to accomplishing the task in the document. -~~~ -{{site.data.alerts.callout_success}} - -{{site.data.alerts.end}} -~~~ + For example, you might use a note to let users know that the `DELETE` statement only deletes rows and that to delete columns you must use `ALTER TABLE`. This helps clarify `DELETE`'s purpose and point users to the right place. -#### Notes +- Use a _warning_ to express that a piece of information is critical to understand to prevent data loss, security vulnerabilities, or unexpected behavior. -Use a note to call attention to a piece of clarifying information; this information should not be crucial to accomplishing the task in the document. + For example, you might include a warning that using `CASCADE` in `DROP INDEX` drops dependent objects without warning. This is critical to prevent users from unexpectedly losing constraints or additional indexes. -For example, you might use a note to let users know that the `DELETE` statement only deletes rows and that to delete columns you must use `ALTER TABLE`. This helps clarify `DELETE`β€˜s purpose and point users to the right place. +**Best practices:** -To insert a note, use the following code: +- Avoid placing callouts adjacent to each other. +- Do not overuse callouts. Most documentation belongs in the body of a page rather than in a callout. -~~~ -{{site.data.alerts.callout_info}} - -{{site.data.alerts.end}} -~~~ +### Images + +Use images to clarify a topic, but only use them as needed. Images are either: + +- **Screenshots:** Depict a UI element. Screenshots should show enough of the UI that the user can easily orient themselves and understand what they are being shown. If a screenshot needs an annotation, use a red box. -#### Warnings + **Note:** Screenshots are difficult to keep current, and impact accessibility. Use a screenshot only if it is necessary for the user to accomplish a task or understand a feature. For example, in a page on troubleshooting cluster performance, a screenshot of a Contention metric graph in the DB Console might be used to depict a cluster with high contention. The same screenshot would not be necessary in a reference topic about the DB Console user interface. -Use a warning to express that a piece of information is critical to understand to prevent data loss, security vulnerabilities, or unexpected behavior. + To optimize accessibility and SEO, a screenshot should be accompanied by text and [alt-text](#write-accessible-documentation) describing its contents. -For example, you might include a warning that using `CASCADE` in `DROP INDEX` drops dependent objects without warning. This is critical to prevent users from unexpectedly losing constraints or additional indexes. +- **Diagrams:** Visualize a complicated mechanism. Diagrams should not reproduce such complexity, and can simplify a process. A diagram should be easy to follow. -To insert a warning, use the following code: + The Docs team uses the following tools to compose diagrams: -~~~ -{{site.data.alerts.callout_danger}} - -{{site.data.alerts.end}} -~~~ + - [Monodraw](https://monodraw.helftone.com/) + - [Omnigraffle](https://www.omnigroup.com/omnigraffle) -#### CockroachDB version callout + Icons for diagrams can be sourced from: https://github.com/cockroachlabs/cockroach-studios/tree/main/icons + +### Videos + +Like images, use videos to clarify a topic, but only use them as needed. Typically, videos should be hosted on the official [CockroachDB YouTube page](https://www.youtube.com/@cockroachdb) and are surfaced by our Marketing team. -A custom callout at the top of the CockroachDB Cloud Release Notes displays the CockroachDB version that Cloud clusters are running. -It should not be used anywhere else. +Place videos under their own page heading. -~~~ -{{site.data.alerts.callout_version}} - -{{site.data.alerts.end}} -~~~ +### Include files + +Sometimes content needs to be duplicated across **two or more pages** in the documentation. For example, there may be several pages that need the same cluster setup, but describe how to use different features. Or a [callout](#callout) needs to be added to several different pages. + +In these situations, use an [_include file_](https://jekyllrb.com/docs/includes/). An include file is a separate Markdown file (stored in `_includes/some/shared-file.md`) whose content is shared across multiple pages. + +For information on include file syntax, refer to the [Markdown Guide](MarkdownGuide.md#include-files). + +**Note:** Using include files adds complexity to the docs site architecture and build process. Consider linking to an existing page or subheading rather than using an include file. + +### GitHub links + +[Release notes](https://www.cockroachlabs.com/docs/releases/index.html), [technical advisories](https://www.cockroachlabs.com/docs/advisories/index.html), and [known limitations](https://www.cockroachlabs.com/docs/stable/known-limitations.html) contain links to individual GitHub issues and pull requests. + +Reference issues and pull requests by their corresponding number, prepended with `#`. + +**Example:** `[#1](https://github.com/cockroachdb/docs/pull/1)` ### Known limitations @@ -315,15 +449,15 @@ It should not be used anywhere else. Sometimes CockroachDB does not behave the way that users expect it to behave. These deviations from expected behavior can be in the form of: -- A difference in syntax between CockroachDB and [SQL Standard](https://blog.ansi.org/2018/10/sql-standard-iso-iec-9075-2016-ansi-x3-135) -- A difference in the behavior of CockroachDB and PostgreSQL -- A feature that is functional, but not yet fully implemented -- A feature that is fully implemented, but has some **long-standing** bugs (i.e., bugs that have existed across patch and/or major releases) -- A feature that limits performance +- A difference in syntax between CockroachDB and [SQL Standard](https://blog.ansi.org/2018/10/sql-standard-iso-iec-9075-2016-ansi-x3-135). +- A difference in the behavior of CockroachDB and PostgreSQL. +- A feature that is functional, but not yet fully implemented. +- A feature that is fully implemented, but has some **long-standing** bugs (i.e., bugs that have existed across patch and/or major releases). +- A feature that limits performance. We list the general differences between CockroachDB and the SQL Standard on our [SQL Feature Support](https://www.cockroachlabs.com/docs/stable/sql-feature-support.html) page, and we provide more details on the differences between CockroachDB and PostgreSQL on our [PostgreSQL Compatibility](https://www.cockroachlabs.com/docs/stable/postgresql-compatibility.html). All other instances of known, but possibly unexpected, database behavior are known as **known limitations**. -Known limitations often have [associated GitHub issues in the `cockroach` repo](https://github.com/cockroachdb/cockroach/issues), meaning the limitation could be resolved one day. *Not all known limitations have GitHub issues, and not all known limitations will be resolved.* +Known limitations often have [associated GitHub issues in the `cockroach` repo](https://github.com/cockroachdb/cockroach/issues), meaning the limitation could be resolved one day. **Not all known limitations have GitHub issues, and not all known limitations will be resolved.** The purpose of documenting known limitations is to help our users know more about using our product safely and effectively. @@ -357,69 +491,4 @@ If the limitation is related to a feature documented elsewhere on our docs site, #### How to document known limitations -Refer to the [wiki](https://cockroachlabs.atlassian.net/wiki/spaces/ED/pages/3516825623/Document+known+limitations). - -### Examples - -Examples help show the feature in action. Examples follow a basic format: - -1. The **Title** should start with a verb and should describe the task the example is outlining. It should use title case. - - **Example:** Create a Table that Mirrors Key-Value Storage - -2. **Introductory information** should be provided if some context is needed to orient the user and can also be used to introduce code blocks. This should be written in a conversational tone. - - **Example:** "CockroachDB is a distributed SQL database built on a transactional and strongly-consistent key-value store. Although it is not possible to access the key-value store directly, you can mirror direct access using a "simple" table of two columns, with one set as the primary key:" - -- **Code blocks** provide executable code samples. - - **Example:** "CockroachDB is a distributed SQL database built on a transactional and strongly-consistent key-value store. Although it is not possible to access the key-value store directly, you can mirror direct access using a "simple" table of two columns, with one set as the primary key: - - ~~~ - > CREATE TABLE kv (k INT PRIMARY KEY, v BYTES); - ~~~ - - When such a "simple" table has no indexes or foreign keys, `INSERT`/`UPSERT`/`UPDATE`/`DELETE` statements translate to key-value operations with minimal overhead (single digit percent slowdowns)." [_Click here to see the rest of the example._](https://www.cockroachlabs.com/docs/stable/create-table.html#create-a-table-that-mirrors-key-value-storage) - -## Content elements - -This section covers various content elements used in CockroachDB documentation. - -### Images - -Use images to clarify a topic, but only use them as needed. Images are either: - -- **Screenshots** - Provide a UI visual. Screenshots should show enough of the UI that the user can easily orient themselves and understand what they are being shown. If a screenshot needs an annotation, use a red box. - - **Note**: Screenshots are difficult to keep current, and impact the accessibility of our documentation. Use a screenshot if it is necessary for the user to accomplish a task or understand a feature. For example, a screenshot of a Contention metric graph in the DB Console could be necessary if it is used as an example of a cluster with high contention in a how-to on troubleshooting performance. It is not necessary in a reference topic about the DB Console user interface. If you add a screenshot to a topic, make sure the topic describes what is being shown in the screenshot for SEO and accessibility. - -- **Diagrams** - Provide a visual of a complicated theory. Diagrams should be simple and easy to read. - -### Videos - -Like images, use videos to clarify a topic, but only use them as needed. Typically, videos should be hosted on the official [CockroachDB YouTube page](https://www.youtube.com/@cockroachdb) and are surfaced by our Marketing team. - -## 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-termilogy) for technical terms that may not be in a dictionary. - -### Directories and folders - -- Use "directory" to refer to a filesystem directory, either locally or in a VM. For example, "Compress the directory into a `zip` archive." -- Use "folder" to refer to a folder within a UI, such as a web UI or an IDE. For example, "Create a folder in your CockroachDB Cloud organization." - -### Technical terminology - -This section logs decisions about software branding and terminology. In general, align third-party branding with that brand's usage. For example, the [PostgreSQL project](https://www.postgresql.org/) uses the word "PostgreSQL" with that capitalization. Add specific guidelines we decide as a team to this table. - -Term | Classification | Note ---- |:---:| --- -Postgres | πŸ”΄ | This is a nickname for PostgreSQL. Use PostgreSQL instead: it's the official name, our docs site and Google treat these as synonyms, and Cmd+F on `Postgres` will still find `PostgreSQL`. -PostgreSQL | 🟒 | Preferred over Postgres. -vxx.x.x | 🟒 | This is the correct way to refer to any version of CockroachDB (for example, `v21.1.8`). Preferred over `version xx.x.x`. When listing a range of versions, separate the first and last version numbers with `to` (for example, `v22.1.0 to v22.1.4`). [Do not use a dash.](#punctuation-rules) - -### Legacy vs. Deprecated - -Use _legacy_ only for our own earlier products, features, or workflows to signal that a newer option is preferred. Avoid using legacy as a pejorative; if no preference is intended, say "earlier" or "previous". Do not use legacy to refer to competitors' products. - -Prefer _deprecated_ when there is an approved plan for end of support and removal. If deprecation is not approved but guidance is needed, you may call the previous option legacy. +Refer to the [wiki](https://cockroachlabs.atlassian.net/wiki/spaces/ED/pages/3516825623/Document+known+limitations). \ No newline at end of file From 4276c883fe97a548a8387756f0915f22a22e57fb Mon Sep 17 00:00:00 2001 From: Ryan Kuo Date: Mon, 8 Sep 2025 17:50:34 -0400 Subject: [PATCH 2/4] fix Avoid/Prefer line break --- StyleGuide.md | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/StyleGuide.md b/StyleGuide.md index 3cfe03c51f7..260e9fa048b 100644 --- a/StyleGuide.md +++ b/StyleGuide.md @@ -58,16 +58,16 @@ In tutorials, where a conversational tone is sometimes helpful, use the second p In page titles and headings, use the imperative mood to name a task. Do not use the gerund form or a noun phrase. -- **Avoid:** Managing Users - **Avoid:** User Management +- **Avoid:** Managing Users + **Avoid:** User Management **Prefer:** Manage Users Do not use "we" to refer to "CockroachDB" or "Cockroach Labs". -- **Avoid:** We support changefeeds. +- **Avoid:** We support changefeeds. **Prefer:** CockroachDB supports changefeeds. -- **Avoid:** We recommend ... +- **Avoid:** We recommend ... **Prefer:** Cockroach Labs recommends ... ### Prescriptive writing @@ -76,37 +76,37 @@ Write in a prescriptive style that clearly guides the user. The user should feel Use active instead of passive voice. -- **Avoid:** Each parameter should be set explicitly. +- **Avoid:** Each parameter should be set explicitly. **Prefer:** Set each parameter explicitly. -- **Avoid:** Additional options can be specified. +- **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. -- **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. +- **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. -- **Avoid:** `table_name`: This parameter is used to specify the name of the table you want to modify. +- **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. Provide guidance rather than leave decisions to the user. Avoid vague phrases like "as you wish" or "of your choice". When user discretion is required, be as explicit as possible to reduce ambiguity and cognitive load. -- **Avoid:** Increase the threshold as needed. +- **Avoid:** Increase the threshold as needed. **Prefer:** Increase the threshold until you see a performance improvement. -- **Avoid:** Define additional settings as desired. +- **Avoid:** Define additional settings as desired. **Prefer:** You can define additional settings in the configuration file. To change the default host and port, set `host` and `port` respectively. To change the path, ... -- **Avoid:** Edit the profile using your preferred text editor. +- **Avoid:** Edit the profile using your preferred text editor. **Prefer:** Edit the profile in a text editor. Avoid vague time estimates. Provide a specific timeframe when possible. -- **Avoid:** You should set the grace period to at least a few minutes. +- **Avoid:** You should set the grace period to at least a few minutes. **Prefer:** Set the grace period to at least 5 minutes. -- **Avoid:** This should take a few moments. When finished, click **Next**. +- **Avoid:** This should take a few moments. When finished, click **Next**. **Prefer:** When finished, click **Next**. Do not use contractions when giving a technical description or instruction. @@ -118,29 +118,29 @@ Do not use "please" when giving an instruction, except when asking the user to g - **Example:** If you need assistance, please contact [support](https://support.cockroachlabs.com/). -- **Avoid:** Please click on the **Next** button. +- **Avoid:** Please click on the **Next** button. **Prefer:** Click **Next**. Do not use language that could be read as presumptuous or condescending. -- **Avoid:** If you aren't willing to do this for some reason, ... +- **Avoid:** If you aren't willing to do this for some reason, ... **Prefer:** If this is not possible, ... -- **Avoid:** Monitoring the cluster is simple. +- **Avoid:** Monitoring the cluster is simple. **Prefer:** Monitor the cluster with the following tools: ### 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. -- **Avoid:** CockroachDB does not yet support column-level privileges. This is planned for a future release. +- **Avoid:** CockroachDB does not yet support column-level privileges. This is planned for a future release. **Prefer:** CockroachDB does not support column-level privileges. ### Latinisms For readability, avoid Latinisms. -- **Avoid:** Select a deployment option, e.g., {{ site.data.products.standard }} or {{ site.data.products.advanced }}. +- **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 }}. ## Word usage guidelines @@ -163,7 +163,7 @@ This section logs decisions about dictionary words to use and avoid. Add specifi - Use "`cockroach`" to refer to the CockroachDB binary. - - **Avoid:** Cockroach process + - **Avoid:** Cockroach process **Prefer:** `cockroach` process ### CockroachDB versions @@ -299,12 +299,12 @@ For links to CockroachDB docs, match the capitalization of the linked content: - Use the [Oxford (aka serial) comma](https://en.wikipedia.org/wiki/Serial_comma). - 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. + - **Avoid:** CockroachDB is a distributed database; it scales horizontally across multiple nodes. **Prefer:** CockroachDB is a distributed database. It scales horizontally across multiple nodes. - Do not end headings with punctuation (for example, periods or colons). - Use periods on either all [list items](MarkdownGuide.md#lists) or none. If some items are sentences or complete a sentence, use periods. - Use colons instead of dashes. - - **Avoid:** **Default** - true + - **Avoid:** **Default** - true **Prefer:** **Default:** true - When listing a range of versions, do not use a dash. Instead, separate the first and last versions with `to` (for example, `v22.1.0 to v22.1.4`). - For singular proper nouns ending in **s**, form the possessive with **'s**. From 2967c9879d003846e8fc6788a708a94807f9c488 Mon Sep 17 00:00:00 2001 From: Ryan Kuo Date: Fri, 19 Sep 2025 12:53:47 -0400 Subject: [PATCH 3/4] address review comments, replace deleted page syntax content, add cross-links --- MarkdownGuide.md | 132 ++++++++++++++++++++++++++++++++++++++--------- StyleGuide.md | 87 +++++++++++++++---------------- 2 files changed, 149 insertions(+), 70 deletions(-) diff --git a/MarkdownGuide.md b/MarkdownGuide.md index 73ae06e2aef..b5fe3cf3367 100644 --- a/MarkdownGuide.md +++ b/MarkdownGuide.md @@ -4,6 +4,14 @@ This guide covers Markdown-specific syntax and formatting conventions used in Co ## Table of Contents +- [Site and Page Structure](#site-and-page-structure) + - [Docs structure](#docs-structure) + - [Pages](#pages) + - [Sidebar](#sidebar) + - [Page TOC](#page-toc) + - [Auto-included content](#auto-included-content) + - [Version tags](#version-tags) + - [Allowed hashes](#allowed-hashes) - [Title](#title) - [Headings](#headings) - [Text formatting](#text-formatting) @@ -46,6 +54,87 @@ This guide covers Markdown-specific syntax and formatting conventions used in Co - [Comments](#comments) - [TODOs](#todos) +## Site structure + +### Docs repository + +Documentation for each CockroachDB version is organized in dedicated directories. For example, CockroachDB v23.1 docs are in `src/current/v23.1` and `src/current/_includes/v23.1`, while CockroachDB API docs are in `src/api`. + +Each page must be a `.md` file written in [Redcarpet](https://github.com/vmg/redcarpet) Markdown. Use lowercase file names with dashes between words. + +**Example:** `name-of-your-file.md` + +### Page headings + +All Markdown pages require YAML front matter: + +```yaml +--- +title: Title of Page +summary: Short description of page for SEO +--- +``` + +**Required fields:** + +Field | Description +------|------------ +`title` | Page heading in title case +`summary` | SEO meta description (50-160 characters) + +**Optional fields:** + +Field | Description | Default +------|-------------|-------- +`toc` | Auto-generates page table of contents | `true` +`toc_not_nested` | Limits TOC to h2 headers only | `false` +`allowed_hashes` | URL hashes that don't correspond to headings | None +`feedback` | Adds Yes/No feedback buttons | `true` +`contribute` | Adds Contribute options | `true` +`twitter` | Enables Twitter campaign tracking | `false` +`no_sidebar` | Removes page sidebar | `false` +`block_search` | Excludes page from search indexing | `false` +`back_to_top` | Adds back-to-top button | `false` +`docs_area` | Analytics area (for example, `get_started`, `reference.sql`) | None +`product_area` | Product area for analytics | None + +### Sidebar + +Each CockroachDB version uses a JSON file to define sidebar navigation. The file is located at `_includes/vXX.Y/sidebar-data/{section}.json`. + +**JSON structure:** + +Field | Type | Description +------|------|------------ +`title` | String | Section or page title in sidebar +`items` | Array | Pages or subsections within a section +`urls` | Array | Page URLs formatted as `/${VERSION}/.html` + +**Example structure:** + +```json +[ + { + "title": "Get Started", + "items": [ + { + "title": "Install CockroachDB", + "urls": ["/${VERSION}/install-cockroachdb.html"] + }, + { + "title": "Start a Local Cluster", + "items": [ + { + "title": "From Binary", + "urls": ["/${VERSION}/start-a-local-cluster.html"] + } + ] + } + ] + } +] +``` + ## Title Set the page title in the `title:` metadata. The title should be in title case. Heading 1 (`#`) is reserved for page titles and **should not** be used in pages. @@ -118,7 +207,7 @@ When linking to a versioned page from a Technical Advisory (in `advisories`), ha ### Custom anchor links -To link to a specific location on a page that is not a heading (e.g., a specific command-line flag in a table), add a manual anchor and use the `id` parameter: +To link to a specific location on a page that is not a heading (for example, a specific command-line flag in a table), add a manual anchor and use the `id` parameter: **Example:** @@ -217,7 +306,7 @@ Notes for usage: Sometimes you may need to escape special characters to achieve proper rendering: -- **Jekyll-reserved characters** (e.g., double `{{ ... }}`) in code blocks: Wrap the specific line(s) with Liquid tags `{% raw %} ... {% endraw %}`. +- **Jekyll-reserved characters** (for example, double `{{ ... }}`) in code blocks: Wrap the specific line(s) with Liquid tags `{% raw %} ... {% endraw %}`. ~~~markdown {% raw %}summary: Instance {{ $labels.instance }} has {{ $value }} tripped per-Replica circuit breakers{% endraw %} @@ -240,7 +329,7 @@ Introduce a list with a sentence and a colon. Use periods at the end of list ite ### Ordered lists -For each item of a **numbered list**, use `1.` followed by a period and a space, e.g., `1. This is a numbered list item`. The HTML renderer will render the steps in the correct order. +For each item of a **numbered list**, use `1.` followed by a period and a space, for example, `1. This is a numbered list item`. The HTML renderer will render the steps in the correct order. ~~~markdown 1. This is the first step. @@ -250,7 +339,7 @@ For each item of a **numbered list**, use `1.` followed by a period and a space, ### Unordered lists -For each item of a **bulleted list**, use one dash followed by one space, e.g., `- This is a bulleted list item`. +For each item of a **bulleted list**, use one dash followed by one space, for example, `- This is a bulleted list item`. ~~~markdown - This is a bullet point. @@ -326,7 +415,7 @@ Use tables to display structured information in an easy-to-read format. We use t ### Markdown tables -If you can keep the table formatting simple (e.g., basic text formatting and using `
` tags for paragraph breaks), create a table using Markdown. This is the preferred table format. +If you can keep the table formatting simple (for example, basic text formatting and using `
` tags for paragraph breaks), create a table using Markdown. This is the preferred table format. To create a table, use pipes (`|`) between columns and at least 3 dashes (`-`) separating the header cells from the body cells. A return denotes the start of the next row. The text within each column does not need to align in order to be rendered correctly, and you can inline Markdown or HTML. @@ -554,36 +643,31 @@ For more information about the `remote_include` tag, see the README in the [jeky ### Filter tabs -On some pages in our docs, there are tabs at the top of the page that will link to different pages at different hyperlinks. For example, in the [Install CockroachDB docs](https://www.cockroachlabs.com/docs/stable/install-cockroachdb.html), there are links to the Mac, Linux, and Windows pages at the top of the page. +Use filter tabs to create navigation between related pages. The [`filter-tabs.md`](https://github.com/cockroachdb/docs/blob/main/src/current/_includes/filter-tabs.md) include generates tabs that link to different pages. -Use [`filter-tabs.md`](https://github.com/cockroachdb/docs/blob/main/src/current/_includes/filter-tabs.md) to specify these tabs for any `cockroachcloud` docs or docs for CockroachDB v21.2 and later. +**Note:** Filter tabs link to different URLs/pages, not tabs within a single page. -**Note:** this include file only produces tabs that link to different URLs/pages. It cannot be used for creating tabs within a single page. +**Setup process:** -The general process to follow and use this is as follows: +1. Identify pages for filter tabs and note their HTML filenames (for example, `install-cockroachdb-mac.html`). -1. Identify each page to be linked from a filter tab. - - Make a note of each HTML page filename (e.g., `install-cockroachdb-mac.html`). - - Draft a tab name (e.g., `Install on Mac`)β€”the text to display on the tab itself. This supports HTML, not Markdown. -2. Create an include Markdown file within `_includes//filter-tabs` with the following structure: - ``` - {% assign tab_names_html = "Tab Name 1;Tab Name 2;Tab Name 3" %} - {% assign html_page_filenames = "page-name-1.html;page-name-2.html;page-name-3.html" %} +1. Create an include file in `_includes//filter-tabs/` with this structure: - {% include filter-tabs.md tab_names=tab_names_html page_filenames=html_page_filenames page_folder= %} + ```liquid + {% assign tab_names_html = "Tab 1;Tab 2;Tab 3" %} + {% assign html_page_filenames = "page1.html;page2.html;page3.html" %} + {% include filter-tabs.md tab_names=tab_names_html page_filenames=html_page_filenames page_folder= %} ``` - - `tab_names_html` is a semicolon-separated list of the HTML-supported tab names. - - `html_page_filenames` is a semicolon-separated list of the page filenames with the `.html` extension. - - `` is `"cockroachcloud"` (with quotes) for any CockroachDB Cloud docs and `page.version.version` (without quotes) for any versioned docs (v21.2 and later). -3. For each page listed in `html_page_filenames`, paste `{% include /filter-tabs/.html %}` in the position where you want the tabs to be included. + +1. Include the filter tabs on each target page: `{% include /filter-tabs/.html %}` ### Technical limitations of include files Include files have the following technical limitations: -- They cannot be used in [Markdown tables](#tables). For example, this is why [the guidance about how to use version tags in tables](#version-tags-tables) is provided. -- A [remote include](#remote-includes) file in another repo that contains an [include file](#include-files) that references something in `cockroachdb/docs` will fail to pull in and render that include file. -- Include files containing a paragraph followed by a code block do not render correctly in the context of both paragraphs and lists in the files they are included from due to a limitation in our [Markdown](#markdown) renderer. +- Cannot be used in [Markdown tables](#markdown-tables) +- Remote includes cannot reference local includes +- Include files with paragraphs followed by code blocks may not render correctly in all contexts ## Tabs diff --git a/StyleGuide.md b/StyleGuide.md index 260e9fa048b..25a573b8d44 100644 --- a/StyleGuide.md +++ b/StyleGuide.md @@ -90,13 +90,13 @@ 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. -Provide guidance rather than leave decisions to the user. Avoid vague phrases like "as you wish" or "of your choice". When user discretion is required, be as explicit as possible to reduce ambiguity and cognitive load. +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. **Prefer:** Increase the threshold until you see a performance improvement. - **Avoid:** Define additional settings as desired. - **Prefer:** You can define additional settings in the configuration file. To change the default host and port, set `host` and `port` respectively. To change the path, ... + **Prefer:** Depending on your configuration, you may need to define additional settings. For example, ... - **Avoid:** Edit the profile using your preferred text editor. **Prefer:** Edit the profile in a text editor. @@ -331,7 +331,7 @@ File names in the CockroachDB docs repo should be lowercase with a dash between ## Page components -This section describes how to approach page elements other than body text. For Markdown-specific syntax and formatting guidelines, refer to the [Markdown Guide](MarkdownGuide.md). +This section describes how to approach page elements other than body text. For Markdown syntax and formatting, refer to the [Markdown Guide](MarkdownGuide.md). ### Code @@ -379,6 +379,8 @@ Ensure that placeholders are placed within backticks: `SET {session variable}`. If the code sample is sensitive to curly bracket characters (as in JavaScript), you can use `<>` instead. +For code block syntax and formatting, refer to the [Markdown Guide](MarkdownGuide.md#code). + ### Callouts CockroachDB docs use three classes of "callouts," which are highlighted blocks of text: tips, notes, and warnings. @@ -397,14 +399,16 @@ CockroachDB docs use three classes of "callouts," which are highlighted blocks o **Best practices:** -- Avoid placing callouts adjacent to each other. +- 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. +For code block syntax and formatting, refer to the [Markdown Guide](MarkdownGuide.md#callouts). + ### Images Use images to clarify a topic, but only use them as needed. Images are either: -- **Screenshots:** Depict a UI element. Screenshots should show enough of the UI that the user can easily orient themselves and understand what they are being shown. If a screenshot needs an annotation, use a red box. +- **Screenshots:** Depict a UI element. Screenshots should only show enough of the UI that the user can easily orient themselves and understand what they are being shown. Exclude UI elements that are not relevant to the screenshot's purpose. If a screenshot needs an annotation, use a red box. **Note:** Screenshots are difficult to keep current, and impact accessibility. Use a screenshot only if it is necessary for the user to accomplish a task or understand a feature. For example, in a page on troubleshooting cluster performance, a screenshot of a Contention metric graph in the DB Console might be used to depict a cluster with high contention. The same screenshot would not be necessary in a reference topic about the DB Console user interface. @@ -414,16 +418,18 @@ Use images to clarify a topic, but only use them as needed. Images are either: The Docs team uses the following tools to compose diagrams: - - [Monodraw](https://monodraw.helftone.com/) - - [Omnigraffle](https://www.omnigroup.com/omnigraffle) + - [Monodraw](https://monodraw.helftone.com/): useful for abstract concept diagrams + - [Omnigraffle](https://www.omnigroup.com/omnigraffle): useful for diagrams with branded elements like logos and colors + + Icons for diagrams can be sourced from the [`cockroach-studios`](https://github.com/cockroachlabs/cockroach-studios/tree/main/icons) repo. The `.gstencil` file in the `icons` directory is an Omnigraffle template listing our branded primary/secondary/extended color palette. - Icons for diagrams can be sourced from: https://github.com/cockroachlabs/cockroach-studios/tree/main/icons +For image syntax and embedding, refer to the [Markdown Guide](MarkdownGuide.md#images). ### Videos Like images, use videos to clarify a topic, but only use them as needed. Typically, videos should be hosted on the official [CockroachDB YouTube page](https://www.youtube.com/@cockroachdb) and are surfaced by our Marketing team. -Place videos under their own page heading. +Place videos under their own page heading. For video embedding syntax, refer to the [Markdown Guide](MarkdownGuide.md#videos). ### Include files @@ -431,11 +437,13 @@ Sometimes content needs to be duplicated across **two or more pages** in the doc In these situations, use an [_include file_](https://jekyllrb.com/docs/includes/). An include file is a separate Markdown file (stored in `_includes/some/shared-file.md`) whose content is shared across multiple pages. -For information on include file syntax, refer to the [Markdown Guide](MarkdownGuide.md#include-files). - **Note:** Using include files adds complexity to the docs site architecture and build process. Consider linking to an existing page or subheading rather than using an include file. -### GitHub links +For include file syntax, refer to the [Markdown Guide](MarkdownGuide.md#include-files). + +### Links + +#### GitHub links [Release notes](https://www.cockroachlabs.com/docs/releases/index.html), [technical advisories](https://www.cockroachlabs.com/docs/advisories/index.html), and [known limitations](https://www.cockroachlabs.com/docs/stable/known-limitations.html) contain links to individual GitHub issues and pull requests. @@ -443,52 +451,39 @@ Reference issues and pull requests by their corresponding number, prepended with **Example:** `[#1](https://github.com/cockroachdb/docs/pull/1)` -### Known limitations - -#### What are known limitations? - -Sometimes CockroachDB does not behave the way that users expect it to behave. These deviations from expected behavior can be in the form of: +#### External links -- A difference in syntax between CockroachDB and [SQL Standard](https://blog.ansi.org/2018/10/sql-standard-iso-iec-9075-2016-ansi-x3-135). -- A difference in the behavior of CockroachDB and PostgreSQL. -- A feature that is functional, but not yet fully implemented. -- A feature that is fully implemented, but has some **long-standing** bugs (i.e., bugs that have existed across patch and/or major releases). -- A feature that limits performance. +When linking to third-party documentation, consider the purpose and maintenance implications. Link to third-party sources for integration workflows, official API references, and tool configurations that change frequently. -We list the general differences between CockroachDB and the SQL Standard on our [SQL Feature Support](https://www.cockroachlabs.com/docs/stable/sql-feature-support.html) page, and we provide more details on the differences between CockroachDB and PostgreSQL on our [PostgreSQL Compatibility](https://www.cockroachlabs.com/docs/stable/postgresql-compatibility.html). All other instances of known, but possibly unexpected, database behavior are known as **known limitations**. - -Known limitations often have [associated GitHub issues in the `cockroach` repo](https://github.com/cockroachdb/cockroach/issues), meaning the limitation could be resolved one day. **Not all known limitations have GitHub issues, and not all known limitations will be resolved.** - -The purpose of documenting known limitations is to help our users know more about using our product safely and effectively. - -#### Where to find known limitations - -Known limitations are generally listed in two places: - -1. (More common) In the `cockroach` repo, as [open issues with the `docs-known-limitations` label, but *not* with the `docs-done` label](https://github.com/cockroachdb/cockroach/issues?q=is%3Aissue+label%3Adocs-known-limitation+-label%3Adocs-done+is%3Aopen). Usually, engineers and product managers add these labels to issues in the weeks leading up to the release. +**Best practices:** -1. (Less common) In the `docs` repo, as [open issues with the `T-known-limitation` label](https://github.com/cockroachdb/docs/issues?q=is%3Aopen+is%3Aissue+label%3AT-known-limitation). +- Link to stable, official documentation pages when possible and ensure links point to the appropriate version of the external product. +- Avoid linking to blog posts or unofficial sources. +- Consider whether a brief explanation in our docs would be more reliable than an external link. -If you come across some behavior that you believe qualifies as a known limitation, first open an issue in the `cockroach` repo, get some engineering/PM feedback on the issue, and then add a `docs-known-limitations` label to an issue. +For link syntax, refer to the [Markdown Guide](MarkdownGuide.md#links). -#### When to document known limitations +## Page sections -Documenting known limitations should happen in the [weeks leading up to a GA release](https://cockroachlabs.atlassian.net/wiki/spaces/ED/pages/402718726/GA+Release+Checklist). +For page headings, refer to the [Markdown Guide](MarkdownGuide.md#page-headings). -You might also need to document a known limitation that is discovered after the GA release. In this case, you will likely be notified by your product area PM and should coordinate with them to determine how best to document the limitation. +### Before you begin -*Avoid documenting known limitations too early. Some "limitations" could be bugs that engineering finds the time to fix during the stability period leading up to a GA release.* +A `Before you begin` section describes prerequisites for following the page content. These may be setup requirements or contextual information that's helpful to the task. Place this section immediately after the page introduction. -#### Who documents known limitations +**Best practices:** -Known limitations for a given product area are documented by the writer assigned to that product area. +- Keep prerequisites specific and actionable. +- Link to relevant setup or configuration pages. +- Use a bulleted list for multiple prerequisites. +- Avoid generic statements like "Have CockroachDB installed" unless the page specifically requires a fresh installation. -#### Where to document known limitations +### Known limitations -Document all known limitations on the [Known Limitations](https://www.cockroachlabs.com/docs/stable/known-limitations.html) page. +A `Known limitations` section describes unexpected database behaviors that differ from SQL standards, PostgreSQL behavior, or expected functionality. Document all known limitations on the [Known Limitations](https://www.cockroachlabs.com/docs/stable/known-limitations.html) page and on feature-specific pages under a dedicated "Known limitations" header. -If the limitation is related to a feature documented elsewhere on our docs site, you should also add the limitation to the page that documents that feature, under a dedicated "Known limitations" header. To avoid duplication, create an [include file](#include-files) in `_includes/vX.X/known-limitations` and include the file in both places. +Document limitations during GA release weeks or when discovered post-release. For detailed procedures, refer to the [documentation wiki](https://cockroachlabs.atlassian.net/wiki/spaces/ED/pages/3516825623/Document+known+limitations). -#### How to document known limitations +### See also -Refer to the [wiki](https://cockroachlabs.atlassian.net/wiki/spaces/ED/pages/3516825623/Document+known+limitations). \ No newline at end of file +A `See also` section contains links to related pages. This is always the last section in a page. \ No newline at end of file From bb4362bfc15f01d1d852f0356de5c417f52d55cb Mon Sep 17 00:00:00 2001 From: Ryan Kuo Date: Fri, 19 Sep 2025 13:02:25 -0400 Subject: [PATCH 4/4] fix page TOCs --- MarkdownGuide.md | 14 +++++--------- StyleGuide.md | 7 ++++++- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/MarkdownGuide.md b/MarkdownGuide.md index b5fe3cf3367..15619dd9692 100644 --- a/MarkdownGuide.md +++ b/MarkdownGuide.md @@ -4,14 +4,10 @@ This guide covers Markdown-specific syntax and formatting conventions used in Co ## Table of Contents -- [Site and Page Structure](#site-and-page-structure) - - [Docs structure](#docs-structure) - - [Pages](#pages) +- [Site structure](#site-structure) + - [Docs repository](#docs-repository) + - [Page headings](#page-headings) - [Sidebar](#sidebar) - - [Page TOC](#page-toc) - - [Auto-included content](#auto-included-content) - - [Version tags](#version-tags) - - [Allowed hashes](#allowed-hashes) - [Title](#title) - [Headings](#headings) - [Text formatting](#text-formatting) @@ -38,7 +34,7 @@ This guide covers Markdown-specific syntax and formatting conventions used in Co - [Tables](#tables) - [Markdown tables](#markdown-tables) - [HTML tables](#html-tables) - - [Markdown vs HTML](#markdown-vs-html) + - [Markdown vs. HTML](#markdown-vs-html) - [Images](#images) - [Videos](#videos) - [Versioning](#versioning) @@ -462,7 +458,7 @@ You can use the following HTML formatting within an HTML table: - Paragraph breaks (`

`) - Lists (`

    ` / `
      ` / `
    • `) -### Markdown vs HTML +### Markdown vs. HTML - Prefer Markdown syntax over HTML when possible for better readability and maintainability. - Use HTML only when Markdown doesn't provide the necessary functionality. diff --git a/StyleGuide.md b/StyleGuide.md index 25a573b8d44..ceec6a46a29 100644 --- a/StyleGuide.md +++ b/StyleGuide.md @@ -31,8 +31,13 @@ Included in this guide: - [Images](#images) - [Videos](#videos) - [Include files](#include-files) - - [GitHub links](#github-links) + - [Links](#links) + - [GitHub links](#github-links) + - [External links](#external-links) +- [Page sections](#page-sections) + - [Before you begin](#before-you-begin) - [Known limitations](#known-limitations) + - [See also](#see-also) For Markdown-specific syntax and formatting guidelines, refer to the [Markdown Guide](MarkdownGuide.md).