From 5104a38f4739a8a1385fa4a95891936d086af4de Mon Sep 17 00:00:00 2001 From: mvm Date: Fri, 5 Jun 2026 18:08:50 -0500 Subject: [PATCH 1/3] [Style Guide] Add rules against LLM-written content patterns --- .agents/references/style-guide.md | 16 ++++++++++++++-- .../notes-and-other-notation-types.mdx | 2 ++ 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/.agents/references/style-guide.md b/.agents/references/style-guide.md index 80dc0d139ad..b6474a3925b 100644 --- a/.agents/references/style-guide.md +++ b/.agents/references/style-guide.md @@ -72,11 +72,22 @@ 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. +- **Avoid condescending qualifiers.** Do not use "simply", "just", or "easily" — they imply the reader is at fault if the task is hard. +- **No throat-clearing introductions.** Do not open pages or sections with "In this guide, you will learn..." or "By the end of this tutorial, you will be able to...". The title and description already state the purpose. +- **No summary paragraphs at the end of sections.** Do not restate what was just written. If the content needs a recap, restructure it. +- **Use second person or imperative, not "we" or "let's".** Write "Run the command" or "You can configure...", not "Let's run the command" or "We will configure...". +- **Do not use "note that" or "it is worth noting" in prose.** If the information warrants calling out, use an admonition. If it does not, fold it into the sentence. +- **Avoid "ensure" as a verb for the reader.** "Ensure that the file exists" is weaker than "The file must exist" or restructuring the step to create the file. Reserve "ensure" for describing what a system guarantees. +- **Do not use "as mentioned above" or "as we saw earlier".** Link to the relevant section instead or restructure to avoid the back-reference. - 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. +- **Em dashes sparingly.** An occasional em dash for a sharp aside is fine; using them in every other sentence is a sign the sentence should be restructured. Prefer a period or a comma. +- **No emojis in prose, titles, headings, or sidebar labels.** Do not use emoji as inline admonition substitutes (`💡 Tip:`, `⚠ī¸ Warning:`, `ℹī¸ Note:`). Always use the `:::note`, `:::caution`, or `:::tip` directive syntax instead. +- **No emoji or symbol columns in tables** (✅, ❌, ⚠ī¸). Use plain text: "Yes", "No", "Partial", or a short phrase. +- **Do not add a manual table of contents in the page body.** Navigation is handled by the sidebar and the on-page TOC. A bulleted list of anchor links at the top of a page is always wrong. +- **Bold is for key terms and UI element names, not for emphasis on arbitrary phrases.** If a sentence needs bold to land its point, rewrite the sentence. ### Abbreviations and acronyms @@ -364,6 +375,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. From 5cbc83b78b868abaf0d7193cd1e48a54cbb1924e Mon Sep 17 00:00:00 2001 From: mvm Date: Fri, 5 Jun 2026 18:11:25 -0500 Subject: [PATCH 2/3] condense LLM pattern rules into single bullet --- .agents/references/style-guide.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/.agents/references/style-guide.md b/.agents/references/style-guide.md index b6474a3925b..9b5316057e1 100644 --- a/.agents/references/style-guide.md +++ b/.agents/references/style-guide.md @@ -73,21 +73,11 @@ reviewed: 2025-01-15 - **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 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. -- **Avoid condescending qualifiers.** Do not use "simply", "just", or "easily" — they imply the reader is at fault if the task is hard. -- **No throat-clearing introductions.** Do not open pages or sections with "In this guide, you will learn..." or "By the end of this tutorial, you will be able to...". The title and description already state the purpose. -- **No summary paragraphs at the end of sections.** Do not restate what was just written. If the content needs a recap, restructure it. -- **Use second person or imperative, not "we" or "let's".** Write "Run the command" or "You can configure...", not "Let's run the command" or "We will configure...". -- **Do not use "note that" or "it is worth noting" in prose.** If the information warrants calling out, use an admonition. If it does not, fold it into the sentence. -- **Avoid "ensure" as a verb for the reader.** "Ensure that the file exists" is weaker than "The file must exist" or restructuring the step to create the file. Reserve "ensure" for describing what a system guarantees. -- **Do not use "as mentioned above" or "as we saw earlier".** Link to the relevant section instead or restructure to avoid the back-reference. - 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. -- **Em dashes sparingly.** An occasional em dash for a sharp aside is fine; using them in every other sentence is a sign the sentence should be restructured. Prefer a period or a comma. - **No emojis in prose, titles, headings, or sidebar labels.** Do not use emoji as inline admonition substitutes (`💡 Tip:`, `⚠ī¸ Warning:`, `ℹī¸ Note:`). Always use the `:::note`, `:::caution`, or `:::tip` directive syntax instead. -- **No emoji or symbol columns in tables** (✅, ❌, ⚠ī¸). Use plain text: "Yes", "No", "Partial", or a short phrase. -- **Do not add a manual table of contents in the page body.** Navigation is handled by the sidebar and the on-page TOC. A bulleted list of anchor links at the top of a page is always wrong. -- **Bold is for key terms and UI element names, not for emphasis on arbitrary phrases.** If a sentence needs bold to land its point, rewrite the sentence. +- **Avoid obviously LLM-written patterns.** Common tells to flag and fix: excessive em dashes; "simply"/"just"/"easily"; throat-clearing intros ("In this guide you will learn..."); closing summaries that restate what was just written; "we"/"let's" instead of imperative; ✅/❌ columns in tables; manual tables of contents in the page body; bold used on arbitrary phrases rather than key terms. ### Abbreviations and acronyms From 54ffadcb99858da8952888dd6a098d026a318192 Mon Sep 17 00:00:00 2001 From: mvm Date: Fri, 5 Jun 2026 18:12:39 -0500 Subject: [PATCH 3/3] rewrite LLM pattern rules to be more direct and complete --- .agents/references/style-guide.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/.agents/references/style-guide.md b/.agents/references/style-guide.md index 9b5316057e1..01ff7f31615 100644 --- a/.agents/references/style-guide.md +++ b/.agents/references/style-guide.md @@ -76,8 +76,17 @@ reviewed: 2025-01-15 - 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 prose, titles, headings, or sidebar labels.** Do not use emoji as inline admonition substitutes (`💡 Tip:`, `⚠ī¸ Warning:`, `ℹī¸ Note:`). Always use the `:::note`, `:::caution`, or `:::tip` directive syntax instead. -- **Avoid obviously LLM-written patterns.** Common tells to flag and fix: excessive em dashes; "simply"/"just"/"easily"; throat-clearing intros ("In this guide you will learn..."); closing summaries that restate what was just written; "we"/"let's" instead of imperative; ✅/❌ columns in tables; manual tables of contents in the page body; bold used on arbitrary phrases rather than key terms. +- **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