From 19fe50339d4df7cd850449dc2d239fe9f443c753 Mon Sep 17 00:00:00 2001 From: AJ Matthews Date: Tue, 29 Sep 2026 16:35:10 +0100 Subject: [PATCH] Improved writing style with rules in the doc-writer skill. --- .agents/skills/doc-writer/SKILL.md | 47 +++++++++++++++++++ .../skills/whatsnew/references/03-critique.md | 1 + .../references/whats-new-template.mdx | 2 +- ...ty-toolkit-integration-doc-writer.agent.md | 1 + .github/instructions/astro.instructions.md | 3 +- 5 files changed, 52 insertions(+), 2 deletions(-) diff --git a/.agents/skills/doc-writer/SKILL.md b/.agents/skills/doc-writer/SKILL.md index 2c3392ab8..219ece8f4 100644 --- a/.agents/skills/doc-writer/SKILL.md +++ b/.agents/skills/doc-writer/SKILL.md @@ -820,6 +820,53 @@ Use consistent terminology throughout: - Use diverse, international examples - Avoid idioms and culturally-specific references +### Prose patterns to avoid + +AI-drafted text falls into recognizable patterns. One instance may be fine but several together make a page read as machine-written and cost the reader time. Before finishing a draft, check for these and rewrite them. + +Sentence structure: + +- Avoid sentences with more than four clauses if possible. Split such a sentence in order to be more direct. +- Avoid framing such as "It's not X, it's Y", "The question isn't X. It's Y", or "Not X. Not Y. Just Z." Instead, say what the thing is. +- Avoid self-answered questions such as "The result? Faster startup." Instead write "Startup is faster." +- Avoid sentence fragments used for emphasis, for example "Local. Fast. Free." Write complete sentences. +- Avoid groups of three used by reflex. List three items only when there are three things. +- Avoid trailing "-ing" clauses that add significance without information. For example, "..., highlighting its flexibility". +- Avoid short phrases hung off a final comma instead of finishing the sentence. +- Avoid "from X to Y" when X and Y aren't ends of a real range. +- Avoid "serves as", "stands as", or "represents" where "is" works. +- Avoid "The first... The second... The third..." prose. Use a list or ``. + +Openings and endings: + +- Don't state a count before a list, such as "Four reasons to...". Instead just state it. +- Don't put evidence before the point. Lead with the point. +- Don't narrate the writing or your reasoning. For example, "It's worth being precise about...". +- Don't defend uncontroversial points or answer objections that nobody raised. +- Cut filler transitions: don't use "It's worth noting", "Importantly", "Interestingly", "Notably", "Here's the thing", "Here's the catch", or similar constructions. + +Word choice and tone: + +- Avoid marketing language: seamless, unlock, elevate, supercharge, game-changing, cutting-edge, unprecedented. Describe what the feature does. +- Do not inflate stakes. For example, "... fundamentally changes how you build software". +- Avoid empty intensifiers: quietly, deeply, fundamentally, remarkably, arguably, truly. +- Avoid stock AI vocabulary: delve, harness, utilize, leverage as a verb (use "use"), streamline, certainly, tapestry, landscape, paradigm, synergy, load-bearing, and "gated" meaning restricted. Use "ecosystem" and "framework" only in their literal technical sense. +- Don't coin labels, such as "the configuration trap" and "port drift", and use them as if they were established terms. +- Don't repeat a distinctive word or phrase from earlier in the page as a callback. +- Avoid analogies, such as "Think of it as...", "It's like a...", "Imagine a world where...", unless the analogy is clearer than the direct explanation. +- Avoid quotable one-liners that carry no information. +- Don't claim something is well known. For example avoid "famously", "notoriously", "a classic", and "as you know". +- Don't cite unnamed sources. Avoid "experts recommend", "many teams find", or similar. Link a specific source or drop the claim. +- Don't list historical companies or technology shifts to build authority. +- Avoid performative candor, such as "And yes, ..." or "To be honest, ...". +- Say where something is defined, stored, or configured, not "where it actually lives". + +Formatting: + +- Don't use em dashes or parenthesis for asides or dramatic pauses. Use commas, a colon, or two sentences. +- Don't start every bullet with a bold phrase. Bold lead-ins are for glossary-style definition lists only (see the glossary format in `.github/instructions/astro.instructions.md`). +- Don't use Unicode arrows (→) or curly quotes in prose. Write "then", "to", or use ``. Arrows are fine inside code and diagrams. + ## Icons and Images ### Icon Location diff --git a/.agents/skills/whatsnew/references/03-critique.md b/.agents/skills/whatsnew/references/03-critique.md index b945bb0f7..b9efaae47 100644 --- a/.agents/skills/whatsnew/references/03-critique.md +++ b/.agents/skills/whatsnew/references/03-critique.md @@ -21,6 +21,7 @@ actionable, severity-ranked findings report. **Makes no edits** — {polish} act - Sections and bullets lead with developer impact, ordered by customer DX. - Positives first; caveats/breaking changes appropriately placed. - KISS — no walls of text, no filler, no marketing superlatives. +- No patterns from doc-writer's "Prose patterns to avoid" list. **What's-new style adherence** - "This release introduces" bullets map **1:1** to the `##` sections, same order. diff --git a/.agents/skills/whatsnew/references/whats-new-template.mdx b/.agents/skills/whatsnew/references/whats-new-template.mdx index 9786ac910..4b96e5075 100644 --- a/.agents/skills/whatsnew/references/whats-new-template.mdx +++ b/.agents/skills/whatsnew/references/whats-new-template.mdx @@ -23,7 +23,7 @@ # placeholders, no researched prose. Content lands in {research}/{polish}. # ───────────────────────────────────────────────────────────────────────────── title: "What's new in Aspire {{VERSION_MAJOR_MINOR}}" -seoTitle: "TODO(polish): 50–60 char social-card title, e.g. What's new in Aspire {{VERSION_MAJOR_MINOR}} — , , and more" +seoTitle: "TODO(polish): 50–60 char social-card title, e.g. What's new in Aspire {{VERSION_MAJOR_MINOR}}: , , and more" description: "TODO(draft): one-sentence, SEO-friendly summary of the headline features in Aspire {{VERSION_MAJOR_MINOR}}. Trimmed to 200 chars for OG." sidebar: label: Aspire {{VERSION_MAJOR_MINOR}} diff --git a/.github/agents/community-toolkit-integration-doc-writer.agent.md b/.github/agents/community-toolkit-integration-doc-writer.agent.md index 713062f12..55b8d145d 100644 --- a/.github/agents/community-toolkit-integration-doc-writer.agent.md +++ b/.github/agents/community-toolkit-integration-doc-writer.agent.md @@ -184,6 +184,7 @@ prerequisites. Do not present the add-on as a standalone service. - Include explanations of what code does, especially for non-obvious patterns - For required parameters, list them with bullet points and descriptions - Reference NuGet packages with the 📦 emoji and link format: `[📦 PackageName](https://nuget.org/packages/PackageName)` +- Follow the "Prose patterns to avoid" list in the `doc-writer` skill (`.agents/skills/doc-writer/SKILL.md`). ### Common patterns diff --git a/.github/instructions/astro.instructions.md b/.github/instructions/astro.instructions.md index a6b0e3aa6..9bc743e3d 100644 --- a/.github/instructions/astro.instructions.md +++ b/.github/instructions/astro.instructions.md @@ -187,6 +187,7 @@ pageActions: false # disable AI/share actions var builder = DistributedApplication.CreateBuilder(args); ``` ```` +- Follow the "Prose patterns to avoid" list in the `doc-writer` skill (`.agents/skills/doc-writer/SKILL.md`). ### Bulleted List Grammar @@ -434,4 +435,4 @@ If a banner is present, dismiss it before any screenshot or visual verification. | `pnpm format` | Prettier formatting | | `pnpm update:integrations` | Sync NuGet integration data | | `pnpm update:samples` | Sync sample data from GitHub | -| `pnpm update:all` | Run all data updates | \ No newline at end of file +| `pnpm update:all` | Run all data updates |