20260318 style guide ai improvements#23382
Conversation
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
Files changed:
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
taroface
requested review from
a team and
taroface
and removed request for
a team
taroface
left a comment
taroface
left a comment
There was a problem hiding this comment.
Bunch of comments, but the most significant to me is the recommendations on some verbs, which may introduce ambiguities for humans/agents.
Also, I think it would help to expand on your Mica methodology in the PR: it's unclear to me whether these are Mica's recommendations for optimizing legibility for itself, or just general style recommendations using our existing guide as the context. It reads more like the latter, but perhaps I'm wrong. If we want to work on the former, I feel like we'd want to work in your findings from the Write the Docs conference (like word limits for pages, etc). Should that be a separate issue?
| **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. |
There was a problem hiding this comment.
Curious about this change!
| - **Avoid:** "due to the fact that" | ||
| **Prefer:** "because" | ||
|
|
||
| - **Avoid:** "at this point in time" |
There was a problem hiding this comment.
We should make sure this recommendation preserves the syntax/concept AS OF SYSTEM TIME, which might possibly be written into prose in some places.
| **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`. |
| - 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. |
There was a problem hiding this comment.
This doesn't seem internally consistent to me. Permissions sound like a "can" use case, since one either does or does not have permissions. This style guidance sounds like it's imagining a phrase like "An admin user may delete the cluster", as in "has the permissions to", which would be confusing.
There was a problem hiding this comment.
Also see below comment on "may". I'm even more concerned than with "should" that formalizing the use of this word will introduce too much ambiguity.
| - 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. |
There was a problem hiding this comment.
I'm not sure "that are impossible" fits here -- isn't that "cannot"?
| **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. |
There was a problem hiding this comment.
| - "The output looks like:" for representative example output. | |
| - "The output looks like the following:" for representative example output. |
| 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. |
There was a problem hiding this comment.
| - "The output includes:" when the example shows a relevant excerpt, not the full output. | |
| - "The output includes the following:" when the example shows a relevant excerpt, not the full output. |
|
|
||
| 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. |
There was a problem hiding this comment.
| - "The command returns:" for exact return values. | |
| - "The command returns the following:" for exact return values. |
| - 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. |
There was a problem hiding this comment.
Should define "major section".
| - 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. |
There was a problem hiding this comment.
I feel like "Check/uncheck" is clearer? "Check the Enable backups option."
There was a problem hiding this comment.
agree on this, i think select is too oblique - "check the checkbox" is simpler
| - "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. |
There was a problem hiding this comment.
typo: "withing" should be "within"
3 participants
These are a bunch of changes to the style guide with two goals: making the style guide itself more readable and usable to AI agents drafting or reviewing docs content, and also improving consistency and specificity across the docs site for better readability by AI agents scanning the docs. These changes were inspired by asking Mica what it would want to see in a style guide as it's reviewing docs PRs. I would love to get a few reviews on this- a lot of it is pretty opinionated and should be subject to discussion before actually being changed. After finalizing changes, I plan on working with Mica to audit existing docs based on the new style guide in order to see how it actually applies the guide in practice.