| name | engineering-writing |
| description | Use when writing something public-facing about this project's engineering. A release announcement, a how-we-built-X deep-dive, a retrospective. Not tied to a release event, and not the mechanical changelog (that's changeset-writing's job). |
Engineering Writing
Narrative, external-facing technical writing, built from reading real engineering blogs end to end and cross-checking against writing-craft, persuasion, and copywriting research, not from generic advice about "good writing." Every technique in the references below is attributed to where it actually came from.
1. Know which register you're writing
An announcement, a how-we-built-X deep-dive, or a retrospective answer different reader questions and take different shapes. Decide this first. references/REGISTERS.md.
2. Diagnose the reader and find what's actually remarkable
What does the reader already believe, and is there a genuinely surprising fact here, or is this the same generic post everyone already wrote? Don't draft until you have a real answer to both. references/PERSUASION-ETHICS.md and references/METHODOLOGY.md.
3. Draft badly and fast, separate from editing
Write the one small section you understand completely, not the whole piece at once. Cutting happens later, as its own pass. references/METHODOLOGY.md.
4. Choose the opening on purpose
Nine real patterns, cold scene, concrete problem, disarming confession, myth-then-dismantle, reframed word, credentials-then-claim, TL;DR, tension, two-sentence tradeoff, pick the one that fits what you actually have. references/OPENINGS-AND-MOMENTUM.md.
5. Structure for momentum
Every sentence's job is to get the next one read. Reveal iteratively, show the alternatives you rejected, end sections with a reason to keep going. references/OPENINGS-AND-MOMENTUM.md.
6. Write in plain voice, cut the slop
Second person, short sentences, a number or name behind every claim. No em dashes, no decorative emoji, no hype words, no AI-tell phrases. Run the checklist before you ship. references/VOICE-AND-SLOP.md.
7. Close with the one thing
A command to run, a link, the sentence you'd want quoted if nothing else gets read. Never a summary of what you already said.
The mechanical, per-change changelog entry is changeset-writing's job, not this one. This skill is for the narrative writing: why it matters, what was hard, what happened, not the record of what changed.
