diff --git a/.agents/references/style-guide.md b/.agents/references/style-guide.md index 80dc0d139ad..01ff7f31615 100644 --- a/.agents/references/style-guide.md +++ b/.agents/references/style-guide.md @@ -72,11 +72,21 @@ reviewed: 2025-01-15 - **Imperative mood for procedures.** Start steps with a verb: "Select", "Run", "Go to". - **Plain language.** Avoid obscure words and jargon. Define acronyms on first use. - **Objective first, then action.** "To create a tunnel, run..." not "Run this command to create a tunnel." -- **Avoid LLM-filler phrases.** Do not use "It's important to note", "leverage", "seamless", "dive into", "straightforward", or similar. +- **Avoid LLM-filler phrases and marketing language.** Do not use: "It's important to note", "leverage", "seamless", "dive into", "straightforward", "robust", "powerful", "cutting-edge", "unlock", "out of the box", "at a glance", or similar. Write what the thing actually does. - Replace `e.g.` with "for example" and `i.e.` with "that is". Never use `etc.` — rewrite or list items explicitly. - Do not use "please" in instructions. - Do not use directional language ("above", "below", "on the right") — reference elements by name instead. -- No emojis in page titles, headings, or sidebar labels. +- **No emojis anywhere in docs.** No emoji in prose, titles, headings, sidebar labels, or tables. Do not use emoji as admonition substitutes — `💡 Tip:` and `âš ī¸ Warning:` in prose are not supported patterns. Use `:::tip` and `:::caution` instead. +- **Avoid LLM-written patterns.** These are the most common tells — flag and fix them: + - **Em dashes overused.** One per page is a sign of good writing. One per paragraph is not. Restructure or use a comma or period. + - **Journalistic/magazine voice.** Docs are not blog posts. Cut scene-setting, dramatic framing, and rhetorical questions. Get to the information. + - **Filler qualifiers.** "Simply", "just", "easily", "quickly" — remove them. They add no information and imply the reader is at fault if they struggle. + - **Throat-clearing intros.** "In this guide, you will learn..." and "By the end of this tutorial..." restate the title. Delete them. + - **Closing summaries.** Paragraphs that restate what was just written. Delete them. + - **"We" and "let's".** Use imperative ("Run the command") or second person ("You can configure..."). Not "Let's run" or "We will configure". + - **✅/❌/âš ī¸ in tables.** Use plain text: "Yes", "No", "Partial". + - **Manual tables of contents.** A bulleted list of anchor links at the top of a page is always wrong. The sidebar and on-page TOC handle navigation. + - **Arbitrary bold.** Bold is for key terms and UI element names. If a sentence needs bold to make its point, rewrite the sentence. ### Abbreviations and acronyms @@ -364,6 +374,7 @@ Usage rules: - No more than one admonition of the same type per section. - Do not add a header to admonitions inside numbered step instructions — the background color is sufficient. - Use admonitions sparingly overall. If most of a page is wrapped in them, restructure the content. +- **Do not use emoji as inline admonition substitutes.** Patterns like `💡 Tip:`, `âš ī¸ Warning:`, or `â„šī¸ Note:` in prose are not supported. Always use the `:::note`, `:::caution`, or `:::tip` directive syntax. --- diff --git a/src/content/docs/style-guide/formatting/notes-and-other-notation-types.mdx b/src/content/docs/style-guide/formatting/notes-and-other-notation-types.mdx index 382bab58c8d..488fd6ee5a4 100644 --- a/src/content/docs/style-guide/formatting/notes-and-other-notation-types.mdx +++ b/src/content/docs/style-guide/formatting/notes-and-other-notation-types.mdx @@ -8,6 +8,8 @@ products: When adding a note to a page, always use this special note formatting. There are three types of formatted notes: `note`, `caution`, and `tip`. +Do not use emoji as inline substitutes for admonitions. Patterns like `💡 Tip:`, `âš ī¸ Warning:`, or `â„šī¸ Note:` in prose are not supported — always use the directive syntax shown below. + Here is some additional information about notes: - The color of the note depends on the type of note: `note` is blue, `caution` is yellow, and `tip` is purple. - For every note type, the header text is optional.