---
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](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](references/PERSUASION-ETHICS.md) and [references/METHODOLOGY.md](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](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](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](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](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.