technical-writing
| Field | Value |
|---|---|
| Type | Skill |
| Source | ~/.copilot/skills/technical-writing/SKILL.md |
| Description | Single front door for everything written for people — Markdown/MDX, Mermaid diagrams, code comments, commit messages, and teaching MDX pages built from real design-system components. Absorbs the former markdown, mermaid, and docs-that-teach skills; any request for any of them routes here. Use for any .md/.mdx write or edit (docs, guides, READMEs, release notes, runbooks, teaching pages), any diagram, code comments, prose for non-technical readers. Triggers: “write docs”, “format this markdown”, “draw a diagram”, “fix this mermaid”, “write a status update”, “comment this code”, “teaching doc”, “docs that teach”. Validate with scripts/lint.py —git-changed. NOT for PRDs, user stories, PR descriptions, UI microcopy, or legal prose. |
Bundled Pages
| Group | Name | Source |
|---|---|---|
| References | Code Comments and Commit Messages | ~/.copilot/skills/technical-writing/references/code-comments.md |
| References | Markdown / MDX Best Practices Skill | ~/.copilot/skills/technical-writing/references/markdown.md |
| References | Mermaid Diagram Skill | ~/.copilot/skills/technical-writing/references/mermaid.md |
| References | Natural Voice | ~/.copilot/skills/technical-writing/references/natural-voice.md |
| References | Question Craft — Asking Questions That Get Real Answers | ~/.copilot/skills/technical-writing/references/question-craft.md |
| References | Technical Writing — Style Guide | ~/.copilot/skills/technical-writing/references/style-guide.md |
| References | Technical Writing — Template Index | ~/.copilot/skills/technical-writing/references/templates.md |
| References | The Cast: Jack and Jill | ~/.copilot/skills/technical-writing/references/personas.md |
| References | The Document Pipeline | ~/.copilot/skills/technical-writing/references/pipeline.md |
| References | Voice and Writers | ~/.copilot/skills/technical-writing/references/voice-and-writers.md |
| References Docs That Teach | Docs That Teach — Review Rubric | ~/.copilot/skills/technical-writing/references/docs-that-teach/review-rubric.md |
| References Docs That Teach | MDX Component Map — real @dmwd-io/design-system components | ~/.copilot/skills/technical-writing/references/docs-that-teach/component-map.md |
| References Docs That Teach | Teaching MDX Pages (Docs That Teach) | ~/.copilot/skills/technical-writing/references/docs-that-teach/teaching-mdx-guide.md |
| References Docs That Teach | Understanding GitHub Actions Reusable Workflows | ~/.copilot/skills/technical-writing/references/docs-that-teach/page-template.mdx |
| References Mermaid | Diagram Principles — make the diagram teach | ~/.copilot/skills/technical-writing/references/mermaid/diagram-principles.md |
| References Mermaid | Diagrams for digital service teams | ~/.copilot/skills/technical-writing/references/mermaid/service-team-diagrams.md |
| References Mermaid | Flowchart shapes and icons (Mermaid v11) | ~/.copilot/skills/technical-writing/references/mermaid/flowchart-shapes-and-icons.md |
| References Mermaid | GitOps Mermaid Patterns | ~/.copilot/skills/technical-writing/references/mermaid/gitops-patterns.md |
| References Mermaid | Icons and surfaces | ~/.copilot/skills/technical-writing/references/mermaid/icons-and-surfaces.md |
| References Mermaid | InteractiveMermaid Renderer Constraints | ~/.copilot/skills/technical-writing/references/mermaid/beautiful-mermaid-constraints.md |
| References Mermaid | Mermaid Chart Selection | ~/.copilot/skills/technical-writing/references/mermaid/chart-selection.md |
| References Mermaid | Mermaid Syntax Reference | ~/.copilot/skills/technical-writing/references/mermaid/syntax-reference.md |
| References Mermaid | Mermaid Validation | ~/.copilot/skills/technical-writing/references/mermaid/validation.md |
| References Mermaid Gallery Build | Build_catalog | ~/.copilot/skills/technical-writing/references/mermaid/gallery/build/build_catalog.py |
| References Mermaid Gallery Build | Build_gallery | ~/.copilot/skills/technical-writing/references/mermaid/gallery/build/build_gallery.py |
| References Mermaid Gallery Build | Build_render | ~/.copilot/skills/technical-writing/references/mermaid/gallery/build/build_render.py |
| References Mermaid Gallery Build | Diagrams | ~/.copilot/skills/technical-writing/references/mermaid/gallery/build/diagrams.py |
| References Mermaid Gallery Build | Gallery build pipeline | ~/.copilot/skills/technical-writing/references/mermaid/gallery/build/README.md |
| References Mermaid Gallery Build | Serve | ~/.copilot/skills/technical-writing/references/mermaid/gallery/build/serve.py |
| References Mermaid Gallery Build | Svgs | ~/.copilot/skills/technical-writing/references/mermaid/gallery/build/svgs.json |
| References Templates | Engineering Blog Post Template | ~/.copilot/skills/technical-writing/references/templates/blog-post.md |
| References Templates | Explanation Template | ~/.copilot/skills/technical-writing/references/templates/explanation.md |
| References Templates | FAQ Template | ~/.copilot/skills/technical-writing/references/templates/faq.md |
| References Templates | How-To Guide Template | ~/.copilot/skills/technical-writing/references/templates/how-to.md |
| References Templates | Migration Guide Template | ~/.copilot/skills/technical-writing/references/templates/migration-guide.md |
| References Templates | README Template | ~/.copilot/skills/technical-writing/references/templates/readme.md |
| References Templates | Reference Template | ~/.copilot/skills/technical-writing/references/templates/reference.md |
| References Templates | Release Notes Template | ~/.copilot/skills/technical-writing/references/templates/release-notes.md |
| References Templates | Runbook Template | ~/.copilot/skills/technical-writing/references/templates/runbook.md |
| References Templates | Status Update Template | ~/.copilot/skills/technical-writing/references/templates/status-update.md |
| References Templates | Troubleshooting Guide Template | ~/.copilot/skills/technical-writing/references/templates/troubleshooting.md |
| References Templates | Tutorial Template | ~/.copilot/skills/technical-writing/references/templates/tutorial.md |
| References Templates | User Survey Template | ~/.copilot/skills/technical-writing/references/templates/user-survey.md |
| References Vale Styles TechnicalWriting | Intensifiers | ~/.copilot/skills/technical-writing/references/vale-styles/TechnicalWriting/Intensifiers.yml |
| References Vale Styles TechnicalWriting | IntroHeadings | ~/.copilot/skills/technical-writing/references/vale-styles/TechnicalWriting/IntroHeadings.yml |
| References Vale Styles TechnicalWriting | Latinisms | ~/.copilot/skills/technical-writing/references/vale-styles/TechnicalWriting/Latinisms.yml |
| References Vale Styles TechnicalWriting | PassiveVoice | ~/.copilot/skills/technical-writing/references/vale-styles/TechnicalWriting/PassiveVoice.yml |
| References Vale Styles TechnicalWriting | SentenceLength | ~/.copilot/skills/technical-writing/references/vale-styles/TechnicalWriting/SentenceLength.yml |
| References Vale Styles TechnicalWriting | TermConsistency | ~/.copilot/skills/technical-writing/references/vale-styles/TechnicalWriting/TermConsistency.yml |
| References Vale Styles TechnicalWriting | VagueWords | ~/.copilot/skills/technical-writing/references/vale-styles/TechnicalWriting/VagueWords.yml |
| References Vale Styles TechnicalWriting | Weasel | ~/.copilot/skills/technical-writing/references/vale-styles/TechnicalWriting/Weasel.yml |
| Resources | Lints | ~/.copilot/skills/technical-writing/lints.toml |
| Scripts | Install Tools | ~/.copilot/skills/technical-writing/scripts/install-tools.sh |
| Scripts | Lint | ~/.copilot/skills/technical-writing/scripts/lint.py |
| Scripts | Lint_docs_that_teach | ~/.copilot/skills/technical-writing/scripts/lint_docs_that_teach.py |
| Scripts | Lint_docs_that_teach_frontmatter | ~/.copilot/skills/technical-writing/scripts/lint_docs_that_teach_frontmatter.py |
| Scripts | Markdown_lint | ~/.copilot/skills/technical-writing/scripts/markdown_lint.py |
| Scripts | Markdownlint | ~/.copilot/skills/technical-writing/scripts/markdownlint.json |
| Scripts | Mermaid_lint | ~/.copilot/skills/technical-writing/scripts/mermaid_lint.py |
| Scripts | Prose_lint | ~/.copilot/skills/technical-writing/scripts/prose_lint.py |
| Scripts | Readability | ~/.copilot/skills/technical-writing/scripts/readability.py |
| Scripts | Voice_lint | ~/.copilot/skills/technical-writing/scripts/voice_lint.py |
Source Content
Technical Writing
| Domain | Everything written for people — .md/.mdx, Mermaid diagrams, code comments |
| Role | Document architect and editor; evaluator of all prose output |
| Output | The right document in the right mode, gated clean by scripts/lint.py |
This skill absorbed the former markdown, mermaid, and docs-that-teach skills — their rules live in this skill’s own references, and nothing invokes them separately.
Route by task
| You’re… | Read | Gate with |
|---|---|---|
| Drawing a diagram only | references/mermaid.md + references/mermaid/ | scripts/mermaid_lint.py |
| Fixing Markdown mechanics only | references/markdown.md | scripts/markdown_lint.py |
| Writing or editing a full document | references/pipeline.md — mode, template, workflow | scripts/lint.py --git-changed |
| Picking a template | references/templates.md → one file per type | - |
| Casting a two-person story | references/personas.md — roster + casting rules | - |
| Writing for non-technical readers, or tuning voice | references/voice-and-writers.md | - |
| Checking a doc doesn’t sound like a robot or address the prompter | references/natural-voice.md | scripts/voice_lint.py (advisory) |
| Writing code comments or commit messages | references/code-comments.md (stories exempt) | - |
| Asking users questions (surveys, research) | references/question-craft.md | - |
| Document-level craft (structure, stories, the cut) | references/style-guide.md | - |
| Teaching MDX page from real design-system components | references/docs-that-teach/teaching-mdx-guide.md + references/docs-that-teach/component-map.md | scripts/lint_docs_that_teach.py + scripts/lint_docs_that_teach_frontmatter.py |
| Validating anything already written | - | scripts/lint.py --git-changed (or explicit files) |
References load lazily — a bare diagram or a one-line README fix never pays for the prose pipeline. scripts/lint.py runs every lint registered in lints.toml that matches the changed file types, skips missing tools with a warning, and fails only on required lints. To add a lint, append a [[lint]] block to lints.toml — no code changes.
The five house rules (non-negotiable)
- 8th-grade reading level. Gated by
scripts/readability.py— repeated technical terms are down-weighted, so “Kubernetes” never costs you. Plain words carry complex ideas better than fancy ones. - Paragraphs never exceed 4 sentences. A fifth sentence means two paragraphs, or a list.
- Every
key: valuepair gets its own line. Config, flags, env vars, headers — in a list or code block, never chained inline. - Every document opens with a two-person story, each on its own line, and closes with a useful ending. It is always Jack and Jill (see
references/personas.md): Jack takes the path with friction and hits the problem; Jill takes the path that works and gets the outcome. Never say which is better — let the outcomes show it. The conclusion, after the reader has read the whole thing, gives the lesson each of them learned. Runbooks compress both to one line each; code comments and commits are exempt from both. - Flows, decisions, and lifecycles get a Mermaid diagram. If you wrote “first X, then Y, unless Z” — draw it, per
references/mermaid.md, with a “what to notice” line under every diagram.
Don’t use me for
- PRDs / product specs →
prd-generator. - User stories / acceptance criteria →
agile-product-owner. - PR descriptions / self-review →
pr-review-checklist. - UI microcopy and interface voice →
ux-designer-researcher. - Legal prose (motions, contracts) →
legal-document-drafter. - Architecture decision records → the
adrskill, which owns the ADR template and lifecycle.
Final checklist
- One Diátaxis mode; the right template from
references/templates/was the starting point. - The lede states the why and the payoff in the first two sentences; headings are noun-phrase promises — never “Introduction” / “Overview”.
- Opens with a two-person story, each on its own line, cast from
references/personas.md; closes with a useful ending (one line each for runbooks; neither for code comments). - Flows and decisions drawn as Mermaid with a “what to notice” line; multi-layer diagrams pass the shape + muted-color rule in
references/mermaid.md. - Named-thing comparisons use headings; every
key: valuepair on its own line; empty table cells get-. - Code runs on the stated version; no invented APIs; unverifiable claims marked
[TODO]. - Cut 20% — adjectives replaced by examples.
- Reads like it was written for its actual reader, not for whoever asked for it — no thank-yous, no “as requested,” no bare “human” outside a direct quote (
references/natural-voice.md). - Saved under
docs/<subfolder>/(README.mdexcepted). -
scripts/lint.py --git-changedexits 0; advisory findings read and weighed, not dismissed. - For a teaching MDX page: components verified against
references/docs-that-teach/component-map.md(never invented), essential content survives outside Tabs/Accordion, a “what to notice” line sits under every visual, and it passesreferences/docs-that-teach/review-rubric.md.
Pointers
references/pipeline.md— the full document workflow: mode, template, drafting steps, gates, optional tooling, CI wiring, self-rubric.references/style-guide.md— audience, readability, formatting, stories, voice, pitfalls.references/personas.md— the persona roster and casting rules for two-person stories.references/voice-and-writers.md— writer models, the journalist’s kit, writing for non-technical readers.references/natural-voice.md— the reader is never the prompter, and other tells that a document sounds machine-written.references/code-comments.md— comments, doc comments, TODOs, commit messages.references/templates.md— the template index; one file per type underreferences/templates/.references/question-craft.md— asking questions that get real answers.references/markdown.md/references/mermaid.md— mechanics and diagram rules, owned in-skill.references/docs-that-teach/— teaching-mdx-guide.md (the former docs-that-teach SKILL.md), component-map.md (real@dmwd-io/design-systemcomponents with verified props), page-template.mdx (gold-standard skeleton), review-rubric.md (the six-dimension publish gate).lints.toml+scripts/lint.py— the lint registry and one-command dispatcher.requirements.txt/Brewfile/scripts/install-tools.sh— optional tooling install (Vale, Proselint, codespell).