Docs That Teach — Review Rubric

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/technical-writing/references/docs-that-teach/review-rubric.md
Description	Not specified

Source Content

Docs That Teach — Review Rubric

Run this before publishing any teaching doc. A page ships only when every dimension passes. Score honestly — a “mostly” is a fail. The dimensions are ordered by how often they catch problems.

Frontmatter

• The page opens with YAML frontmatter carrying title, created, last_updated, tags, tldr, and contributors.
• created and last_updated are ISO dates (YYYY-MM-DD); last_updated is not before created.
• tags and contributors are non-empty lists; tldr is a single line.
• scripts/lint_frontmatter.py exits 0 on the file.

Clarity

• A new engineer can understand the topic from the page alone.
• The main idea is obvious within 30 seconds of landing.
• Every technical term is explained naturally or linked on first use; acronyms are expanded once.
• Plain language at roughly an eighth-grade level: sentences mostly under 20 words, common connective words, real technical terms kept (say git, not “the place where we store code”). readability.py is advisory — act on its long-sentence list.
• The opening summary makes the reader feel “this is worth my time.”

Structure

• A skimmer can follow the whole page through headings, tables, diagrams, and the TL;DR alone.
• Sequential steps are numbered; unordered points are bulleted.
• Named-thing comparisons use #### headings or a comparison table — never bold names in a paragraph.
• Every table cell is filled (- for blanks); every table has a header row.
• Headings are promises, not labels — no Introduction, Overview, or Summary.

Visual learning

• Every diagram, chart, and image teaches something — none is decorative.
• There is at least one visual if the topic involves flow, architecture, ownership, lifecycle, or a decision.
• Each visual has a “what to notice” sentence next to it.
• Charts have a title, labeled axes, and units; diagrams ran through the technical-writing skill’s diagram rules and linter.

Practical use

• There is at least one real, runnable example — not pseudocode.
• Expected output is shown for commands and code.
• At least one common mistake is called out where it bites.
• The key lesson is carried by a short story (claim → vignette → lesson), not just a dry rule — and any real story is true, any hypothetical reads as hypothetical.
• A reader could apply the guidance immediately after reading.

Accessibility

• Exactly one H1; no skipped heading levels.
• Every image has descriptive alt text (never “screenshot”); figures have captions.
• Tables have header rows; large tables are split or reflowed for narrow widths.
• Information is never conveyed by color alone — always paired with text or an icon.
• Link text is descriptive out of context — no “click here” or bare URLs.

Print support

• Nothing essential is hidden inside Tabs or Accordion — print flattens both.
• Every interactive component has a printFallback or an adjacent static equivalent.
• Diagrams are legible in grayscale; nothing depends on color to be understood.
• Tables fit the page width; code blocks wrap or stay readable; figures are not tiny.

Enjoyability

• The page has a point of view and a narrative, not a note dump.
• Every paragraph has at least one highlightable line — a reader would underline, screenshot, or quote it (the highlight test). No paragraph is filler.
• No line strains to be profound — one highlight per paragraph, not a firework in every clause.
• It teaches something memorable — there is a real Key Takeaway or Decision Rule.
• A reader would voluntarily send it to a teammate.
• It reads in ≤ 8 minutes (target 5); if longer, it was split into linked pages.

Component truthfulness

• Every @dmwd-io/design-system component’s props came from the Storybook MCP — none invented.
• No fictional components (<Terminal>, <BeforeAfter>, <DecisionTable>, <Figure>, <Quiz>) — only real exports.
• The markdown linter exits 0; if the repo has an MDX validator, it passes too.