Standardization of content stylistics: what to use and when

[novusnota]

1. When to use bold? Or, if that set is narrower, when not to use bold text?
2. When to use italic?
   • For example, when introducing new terms: https://developers.google.com/style/italics-terms
3. When referencing a button in the interface, use the <kbd> tag as such: Settings (not with bold, italic or quotes)
4. Prefer not to use emojis unless this is a "step-by-step guide" (?)
5. Prefer not to style elements when writing — only do so when editing. The rule of thumb: if the text can live without extra styling and not lose its meaning, so be it.
6. Use parentheses judiciously. That is, prefer not to use them unless necessary, because they often mix in more ideas than the current sentence can handle, disrupting the reading flow.
7. One sentence = one idea.
8. Use <Card> component for on-page navigation and prefer not to use it in any other scenarios. Exception: index.mdx.
9. ...etc.

Each of the points above shall be documented at least in the extended style guide for AI reviews. If the point is frequent enough, we might consider placing it in the short style guide too.

See also:

• Our current, short style guide
• Astro's docs writing and style guide
• Google developer documentation style guide

Related to #81 and #931.

[verytactical]

When to use bold? Or, if that set is narrower, when not to use bold text?

Anywhere you need to grab attention of a reader. Reader's eyes will move between bold words in the article, looking for a relevant place to start reading there.

When to use italic?

Whenever an emphasis is required that shouldn't grab attention of a reader that skims the article.

When referencing a button in the interface, use the <kbd> tag as such: Settings (not with bold, italic or quotes)

Yes

Prefer not to use emojis unless this is a "step-by-step guide" (?)

Prefer not to use emojis, full stop. Every use of emojis should have a reason. For example, ecosystem/sdks requires a small mark that would tell this library is somehow preferred. This kind of preference is usually denoted with a ⭐. Adding a ▶ to denote this is a link to a video is neither conventional, nor justified.

Prefer not to style elements when writing — only do so when editing. The rule of thumb: if the text can live without extra styling and not lose its meaning, so be it.

Yes. The same applies to

• headers
• <Aside>
• literally everything.

If we can do away without it, remove it.

Use parentheses judiciously. That is, prefer not to use them unless necessary, because they often mix in more ideas than the current sentence can handle, disrupting the reading flow.

AFAIK they're also frowned upon by native speakers.

One sentence = one idea.

Yes.

Use component for on-page navigation and prefer not to use it in any other scenarios. Exception: index.mdx.

Please don't use <Card> component. It's just some extra 1 pixel borders that break the flow of the text, waste space, and are as unpleasant to deal with in MDX as it is to try to read them in an article.

Modern screens can assign more physical pixels to a CSS 1px. Browsers can basically do anything they want due to current DPI, zoom, and weather forecast. From a design point of view single-pixel borders are a no-no.

Here's a perfect example of a design that uses them.

[Gusarich]

Also I think we need to change the specified structure for risk warnings. #972 (comment)

Maybe just require some form of a "warning" but not in such a "formal" way?

And for pages with many potentially dangerous actions, we could add a proper warning somewhere on top and for each individual point just a small one or something like this.