diff --git a/.claude/skills/write-blog/SKILL.md b/.claude/skills/write-blog/SKILL.md new file mode 100644 index 0000000..3d24064 --- /dev/null +++ b/.claude/skills/write-blog/SKILL.md @@ -0,0 +1,53 @@ +--- +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 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 + +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..1db13c8 --- /dev/null +++ b/.claude/skills/write-docs/SKILL.md @@ -0,0 +1,56 @@ +--- +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 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 + +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..0072189 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: ****. ## 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.