full pass on Style Guide #20307
full pass on Style Guide #20307
Conversation
✅ Deploy Preview for cockroachdb-docs canceled.
|
Files changed:
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
taroface
force-pushed
the
style-guide-update
branch
from
ff15278 to
4276c88
Compare
|
|
||
| ### Third-party products | ||
|
|
||
| In general, align third-party branding with that brand's usage. Do not use the shortened versions of product names. |
There was a problem hiding this comment.
i have received feedback in the past to avoid linking to 3rd party products' docs unless absolutely necessary for clarity. IDK if that is appropriate for inclusion in this section, or if we would like to discuss it more separately. I don't have a strong opinion except that such external links often break because humans break their websites constantly
There was a problem hiding this comment.
I have the possibly total opposite opinion, which is that I don't want us to be responsible for documenting third party product flows and would rather link out to their documentation wherever possible for those. Easier to identify and fix a broken link than correct text on our site that describes an outdated third-party procedure.
There was a problem hiding this comment.
oh sure, totes agreed. the vibe was not about integration docs per se (in which case, yes please someone else do them) but just general linking vs not
There was a problem hiding this comment.
Linking out to external products is absolutely necessary for things like migration docs. I think I can add some follow-up guidance on external links that is consistent with both of your comments; stay tuned.
|
|
||
| - 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, ... |
There was a problem hiding this comment.
This implies that we should spell out every configuration option available, which can get unwieldy fast. Especially in deployment guides where we may want to offer a "one size fits all" initial configuration but leave room for optional configurations. In those circumstances I would rather link out if there's a good docs target or even leave out the sentences after the first generic one.
There was a problem hiding this comment.
I think I get you, but could you provide an example of what you're suggesting here?
There was a problem hiding this comment.
https://www.cockroachlabs.com/docs/stable/deploy-cockroachdb-with-cockroachdb-operator#initialize-the-cluster Step 6 here is a hand-wavey note that essentially says "if you know you need to make other changes to your configuration yaml, now is a good time to make those" without going into details of every option. I believe it's compliant with the first sentence of your Prefer example, but it refers to only a couple example configs and doesn't have task-oriented sentences like the "To change the ... set ..." in that example.
I would just want to clarify in the style guide if this approach is acceptable when there are too many specific configs to spell out in that single instruction
There was a problem hiding this comment.
I see. The style guidance here is specifically intended to guardrail us against hand-waving. It's of course not possible to mention or prescribe a value for every configurable detail of every customer's deployment. But from past/ongoing experiences, phrases like "If you know you need ..." or "Modify other relevant parts of the configuration ..." will prompt at least some customers to respond, "How do I know I need to?" and "Which parts are relevant?". A subtle balancing act might be to simply state in a callout that "Depending on your configuration, you may need to set additional parameters in the XYZ fields". They might still ask the question, but won't be led to feel they should already know the answer.
@Flat5flat9 wondering if you have any thoughts here.
There was a problem hiding this comment.
I would hope that we have guidance somewhere that we could link to? Then it could have links like "Depending on [your configuration](link to guidance), you may need to set additional parameters in the XYZ fields"
There was a problem hiding this comment.
This brings us back to asking how much guidance we can reasonably provide. I feel there must be a way to indicate there's a limit without appearing to hand-wave it away. I'll think on the guidance.
| - Databases on the cluster | ||
| - Jobs running on the cluster | ||
|
|
||
| ## Inclusivity |
There was a problem hiding this comment.
Suggest a quick subsection under here to avoid idioms and terminology that could be confusing when auto-translated (which should be assumed given that we don't have a localization team).
Suggest something like:
### Avoid idioms and other difficult-to-translate terminology
The majority of our non English-speaking readers use a browser translation tool to read our documentation in a preferred language. Avoid using idioms or non industry-standard terms that these tools may translate literally.
- **Avoid:** Configure roles and permissions to draw a line between allowed and disallowed actions.
**Prefer:** Configure roles and permissions to allow and disallow actions.
|
|
||
| Reference issues and pull requests by their corresponding number, prepended with `#`. | ||
| - **Example:** `SELECT * FROM TABLE {mytable};`. |
There was a problem hiding this comment.
Suggest also adding an example from the API docs where these are commonly used in URLs, like
- **Example:** `--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/nodes`
|
|
||
| To insert a note, use the following code: | ||
| - Avoid placing callouts adjacent to each other. |
There was a problem hiding this comment.
I would add "Avoid placing a callout immediately below a header without introductory text for the section" but IIRC we've done that in a couple places.
|
|
||
| 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. |
There was a problem hiding this comment.
| - **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. If a screenshot needs an annotation, use a red box. |
Would like to emphasize not including page elements that are not relevant to the screenshot's purpose.
|
|
||
| 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. |
There was a problem hiding this comment.
Could we include an example here showing the correct syntax to do this? Like:
<img src="{{ 'images/v24.2/topology-patterns/topology_multi-region_hardware.png' | relative_url }}" alt="Multi-region hardware setup" style="max-width:100%" />
There was a problem hiding this comment.
Hmm this should be in the separate MarkdownGuide.md, which was largely necessary, but did indeed cause some awkward splits. I'll see what I can do to mitigate this.
| - [Monodraw](https://monodraw.helftone.com/) | ||
| - [Omnigraffle](https://www.omnigroup.com/omnigraffle) |
There was a problem hiding this comment.
Suggest appending the use cases for each. IMO these are
- Monodraw (useful for abstract concept diagrams)
- Omnigraffle (useful for diagrams with branded elements like logos and colors)
|
|
||
| #### CockroachDB version callout | ||
| Icons for diagrams can be sourced from: https://github.com/cockroachlabs/cockroach-studios/tree/main/icons |
There was a problem hiding this comment.
| Icons for diagrams can be sourced from: https://github.com/cockroachlabs/cockroach-studios/tree/main/icons | |
| Icons and colors for diagrams can be sourced from: https://github.com/cockroachlabs/cockroach-studios/tree/main/icons |
There was a problem hiding this comment.
The .gstencil file in that directory is an Omnigraffle template listing our branded primary/secondary/extended color palette.
| - 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. |
There was a problem hiding this comment.
There was a problem hiding this comment.
@rmloveland This was directed specifically at you (jk it was already there)
|
|
||
| ## Page components |
There was a problem hiding this comment.
i think this was a separate PR but i am kinda bummed that we removed the stuff about consistent page structure, e.g.
- before you begin
- ...
- see also
since i think there is a lot of value of having ~all the pages in the docs share a rough structure for easier scanning, since folks aren't usually "reading" carefully but "scanning"
however maybe this doesn't matter in agent world (tm)
There was a problem hiding this comment.
I don't recall seeing or removing those sections. I see that some TOC links corresponding to those were removed in #20170, but I think that content was previously removed (not sure if by me). I'll dig around for it in the git history. Thank you for raising this!
There was a problem hiding this comment.
looks like it was removed in this PR: https://github.com/cockroachdb/docs/pull/19334/files
There was a problem hiding this comment.
Thanks! I probably cut too broad a swath there. I'll see what I can put back.
|
|
||
| | Avoid | Prefer | | ||
| |----------|------------| | ||
| | Postgres | PostgreSQL | |
There was a problem hiding this comment.
maybe not for this PR but i've long believed we need to revisit this, even the PG docs themselves are like "Postgres is fine"
https://www.postgresql.org/docs/current/history.html#HISTORY-POSTGRESQL
Postgres is still considered an official project name, both because of tradition and because people find it easier to pronounce Postgres than PostgreSQL.
Uh oh!
There was an error while loading. Please reload this page.