From 0e71e411a3e0261069ed37af6ed5c43af79cb40d Mon Sep 17 00:00:00 2001 From: Josh Smith <6895577+joshsmithxrm@users.noreply.github.com> Date: Sun, 19 Apr 2026 03:46:02 -0500 Subject: [PATCH 1/2] =?UTF-8?q?chore(claude-md):=20prune=20CLAUDE.md=20per?= =?UTF-8?q?=20hygiene=20audit=20(B2=20=E2=80=94=20companion=20to=20ppds#XX?= =?UTF-8?q?X)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Applies the per-line verdicts from the v1-launch hygiene audit (.plans/retro/findings/E-claudemd-hygiene.md in the ppds repo). BEFORE/AFTER: 62 lines -> 29 lines. DELETE: - Title duplication (README has it). - Structure listing (visible in directory tree). - Key Files (docusaurus.config.ts/sidebars.ts are obvious). - "Write marketing fluff" / "Write for the user goal" — vague aspirations. - "Use screenshots without alt text" — markdownlint MD045 enforces. MOVE: - Doc Types (Diátaxis) + Style rules -> .claude/skills/write-docs/SKILL.md (NEW). - Blog Voice -> .claude/skills/write-blog/SKILL.md (NEW). KEEP (passes 4-question test): - Commands table (3 npm scripts Claude cannot guess). - 2 NEVERs (don't document unimplemented features, don't duplicate code). - 3 ALWAYs (test code examples, link to source, use canonical terminology). - Branding pointer (canonical name list). - Pointer to the cross-repo governance doc. [claude-md-reviewed: 2026-04-18] Companion PR to PPDS feat/claudemd-governance. --- .claude/skills/write-blog/SKILL.md | 50 ++++++++++++++++++++++++ .claude/skills/write-docs/SKILL.md | 62 ++++++++++++++++++++++++++++++ CLAUDE.md | 54 ++++++-------------------- 3 files changed, 123 insertions(+), 43 deletions(-) create mode 100644 .claude/skills/write-blog/SKILL.md create mode 100644 .claude/skills/write-docs/SKILL.md diff --git a/.claude/skills/write-blog/SKILL.md b/.claude/skills/write-blog/SKILL.md new file mode 100644 index 0000000..0bcc43d --- /dev/null +++ b/.claude/skills/write-blog/SKILL.md @@ -0,0 +1,50 @@ +--- +name: write-blog +description: Authoring blog posts in ppds-docs — first-person voice, technical narrative. Use when drafting a blog post or release recap. +--- + +# Write Blog + +Voice and structure for the blog. Different from `write-docs` — blog +posts are personal, narrative, and opinionated. + +## When to Use + +- Writing a new blog post under `blog/` +- Drafting a release recap or technical deep-dive +- Reviewing a blog PR + +## Voice + +- **First person singular** ("I discovered...", "we ran into..." for + collaborative posts). +- **Conversational but technical** — read like a smart colleague at a + whiteboard, not a marketing brochure. +- **Show the struggle, not just the solution.** The interesting part is + what didn't work and why; the fix is usually one paragraph. +- **Include real numbers.** "5x faster" is fine; "much faster" is not. + Cite the benchmark, the row count, the wall-clock seconds. + +## Structure + +A typical post: + +1. Hook — the question or problem that prompted the work, in 2–3 + sentences. +2. What you tried first — the wrong path, why it seemed right at the + time. +3. The pivot — the insight that changed the approach. +4. The solution — code, numbers, links to source. +5. What's next — what this enables, what is still open. + +## What to Avoid + +- Marketing fluff ("revolutionary", "industry-leading"). Cut on sight. +- Posts that are only the solution. The insight is what readers come for. +- Screenshots without alt text. The lint blocks them anyway, but write + alt text well — describe the data shown, not "screenshot of dashboard". + +## Why This Lives in a Skill, Not CLAUDE.md + +Blog voice only matters when writing blog posts. Loading it every session +would crowd out rules that always apply. diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md new file mode 100644 index 0000000..ef21449 --- /dev/null +++ b/.claude/skills/write-docs/SKILL.md @@ -0,0 +1,62 @@ +--- +name: write-docs +description: Authoring docs in ppds-docs — Diátaxis classification, voice, style. Use when writing or restructuring tutorials, guides, reference, or concept docs. +--- + +# Write Docs + +Conventions for the documentation site. Triggers when authoring or +reorganizing prose under `docs/`. + +## When to Use + +- Writing a new doc page +- Refactoring an existing page that does not fit cleanly in one Diátaxis bucket +- Reviewing a PR that touches `docs/` + +## Diátaxis Classification + +Every doc fits exactly one of these buckets. If you cannot pick one, the +doc needs to be split. + +| Type | Purpose | Voice | +|------|---------|-------| +| Tutorial | Learning-oriented, step-by-step | Hand-hold the reader through a complete experience | +| Guide | Task-oriented, goal-focused | Show the most direct path to the user's goal | +| Reference | Information-oriented, complete | Be exhaustive and predictable; no opinions | +| Concept | Understanding-oriented, explains why | Explain the model and tradeoffs; no procedure | + +Mixing types in one page is the most common drift. A tutorial that becomes +a reference table is two pages. + +## Style Rules + +- **Second person** ("you can...") for tutorials and guides. +- **Third person** for reference and concept docs. +- **Present tense, active voice.** +- **Short paragraphs** — 3–4 sentences max. Long paragraphs scan poorly. +- **Code examples are copy-pasteable** — no placeholders without explicit + callouts; assume the reader will paste verbatim and fix mismatches in + prod. +- **Test every code example** at least once before merge. Stale examples + are the #1 source of bug reports. +- **Link to source code** for implementation details rather than + duplicating logic in prose. +- **Use consistent terminology** — see `.claude/rules/branding.md` for the + canonical name list (PPDS vs Power Platform Developer Suite, surface + names, etc.). + +## Doc Lifecycle + +1. **Draft** under `docs//.md` with the right Diátaxis bucket. +2. **Add to sidebar** in `sidebars.ts` if surfacing to users. +3. **Run the docs site locally** (`npm start`) and proof at + `localhost:3000`. +4. **Submit PR** — the docs CI runs link-checking and broken-image checks. + +## Why This Lives in a Skill, Not CLAUDE.md + +Doc-authoring conventions only matter when writing prose. Loading them +into every Claude session in the docs repo would crowd out genuinely +global rules. The skill auto-loads when it is needed; otherwise it sits +idle. diff --git a/CLAUDE.md b/CLAUDE.md index b58ee26..3f70be6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,20 +1,19 @@ # PPDS Docs -Documentation site for Power Platform Developer Suite. +Documentation site for Power Platform Developer Suite (Docusaurus). + +Governance for THIS file: **`../ppds/docs/CLAUDE-MD-GOVERNANCE.md`**. ## NEVER -- Write marketing fluff - be technical and direct -- Document features before they're implemented -- Duplicate content that exists in code (link instead) -- Use screenshots without alt text +- Document a feature that is not yet implemented in PPDS. +- Duplicate content that already exists in code or specs — link instead. ## ALWAYS -- Write for the user's goal, not the feature -- Include working code examples (test them!) -- Link to source code for implementation details -- Use consistent terminology (see `.claude/rules/branding.md`) +- Test every code example before merge — broken examples are the #1 source of bug reports. +- Link to source code for implementation details rather than re-explaining logic. +- Use canonical terminology — see `.claude/rules/branding.md` for the name list. ## Commands @@ -24,38 +23,7 @@ Documentation site for Power Platform Developer Suite. | `npm run build` | Production build | | `npm run typecheck` | TypeScript validation | -## Doc Types (Diátaxis) - -| Type | Purpose | -|------|---------| -| Tutorial | Learning-oriented, step-by-step | -| Guide | Task-oriented, goal-focused | -| Reference | Information-oriented, complete | -| Concept | Understanding-oriented, explains why | - -## Structure - -- `docs/getting-started/` - First 5 minutes -- `docs/guides/` - How to... (task-oriented) -- `docs/reference/` - CLI/Libraries/MCP reference -- `docs/concepts/` - Architecture explanations - -## Key Files - -- `docusaurus.config.ts` - Site configuration -- `sidebars.ts` - Navigation structure -- `.claude/rules/branding.md` - Colors, voice, terminology - -## Style - -- Second person ("you can...") -- Present tense, active voice -- Code examples should be copy-pasteable -- Short paragraphs (3-4 sentences max) - -## Blog Voice +## Authoring -- First person singular ("I discovered...") -- Conversational but technical -- Show the struggle, not just the solution -- Include real numbers +For Diátaxis classification, voice, and style: see the `write-docs` skill. +For blog posts: see the `write-blog` skill. From f681f0a40d6d27f7c0134d60be6b01f25a01ae38 Mon Sep 17 00:00:00 2001 From: Josh Smith Date: Sun, 19 Apr 2026 04:27:26 -0500 Subject: [PATCH 2/2] docs: address gemini review feedback (path link, wording, dedupe, alt text) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CLAUDE.md L5: replace sibling relative path with absolute GitHub URL so the governance reference resolves on GitHub UI, in CI, and from workspace-restricted AI agents. - .claude/skills/write-docs/SKILL.md L38–47: rewrite the copy-pasteability rule to remove the ambiguous "fix mismatches in prod" phrasing, and delete the duplicated test/link/terminology bullets that already live in CLAUDE.md ALWAYS (the exact anti-pattern PR-B is preventing). - .claude/skills/write-blog/SKILL.md L44–48: distinguish informative images (need descriptive alt text) from decorative images (alt="") per WCAG. [claude-md-reviewed: 2026-04-19] Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/skills/write-blog/SKILL.md | 7 +++++-- .claude/skills/write-docs/SKILL.md | 14 ++++---------- CLAUDE.md | 2 +- 3 files changed, 10 insertions(+), 13 deletions(-) diff --git a/.claude/skills/write-blog/SKILL.md b/.claude/skills/write-blog/SKILL.md index 0bcc43d..3d24064 100644 --- a/.claude/skills/write-blog/SKILL.md +++ b/.claude/skills/write-blog/SKILL.md @@ -41,8 +41,11 @@ A typical post: - Marketing fluff ("revolutionary", "industry-leading"). Cut on sight. - Posts that are only the solution. The insight is what readers come for. -- Screenshots without alt text. The lint blocks them anyway, but write - alt text well — describe the data shown, not "screenshot of dashboard". +- Screenshots and informative images without alt text. Write alt text + that describes what the user should perceive — the data shown, not + "screenshot of dashboard". Decorative images (banners, dividers) should + use an empty alt attribute (`alt=""`) per WCAG so screen readers skip + them. ## Why This Lives in a Skill, Not CLAUDE.md diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md index ef21449..1db13c8 100644 --- a/.claude/skills/write-docs/SKILL.md +++ b/.claude/skills/write-docs/SKILL.md @@ -35,16 +35,10 @@ a reference table is two pages. - **Third person** for reference and concept docs. - **Present tense, active voice.** - **Short paragraphs** — 3–4 sentences max. Long paragraphs scan poorly. -- **Code examples are copy-pasteable** — no placeholders without explicit - callouts; assume the reader will paste verbatim and fix mismatches in - prod. -- **Test every code example** at least once before merge. Stale examples - are the #1 source of bug reports. -- **Link to source code** for implementation details rather than - duplicating logic in prose. -- **Use consistent terminology** — see `.claude/rules/branding.md` for the - canonical name list (PPDS vs Power Platform Developer Suite, surface - names, etc.). +- **Code blocks must be correct and ready for use.** Assume the reader + will copy them verbatim — no `todo`, no `fix in prod`, no untested + placeholders. If a value must be substituted, surface it with an + explicit callout immediately above the block. ## Doc Lifecycle diff --git a/CLAUDE.md b/CLAUDE.md index 3f70be6..0072189 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,7 +2,7 @@ Documentation site for Power Platform Developer Suite (Docusaurus). -Governance for THIS file: **`../ppds/docs/CLAUDE-MD-GOVERNANCE.md`**. +Governance for THIS file: ****. ## NEVER