Engineering Blog Post Template

Field	Value
Type	Skill Resource
Source	~/.copilot/skills/technical-writing/references/templates/blog-post.md
Description	Not specified

Source Content

Engineering Blog Post Template

Narrative with a payoff. Earns attention, then teaches. Composite form: explanation carried by story.

Skeleton

# {{Title that promises value}}

{{Hook — a problem or a surprising observation. A two-person story makes
the strongest hook: Jack hits the problem, Jill finds the path.}}
{{Stakes — why it matters now. Promise — what the reader will learn.}}

## The challenge

{{The specific problem and why existing solutions fall short. A named
scene beats an abstract claim: what was on the dashboard, who got paged.}}

## The approach

{{The solution at a high level and the insight that made it possible.}}

{{Mermaid diagram of the before/after architecture — follow the diagram rules in ../mermaid.md.}}
_{{What to notice in the diagram.}}_

## How it works

{{Technical detail with runnable examples and the decisions behind them.}}

## Results

{{Quantified outcomes and anything that surprised you.}}

## What I'd do differently

{{Honest lessons; how the reader can apply this.}}

## The useful ending

{{One or two sentences, after everything above: what each person from the
opening walked away with, now that this is written down.}}

Rules for this template

• The hook is the first two sentences — no wind-up, no “in this post I will”.
• Real stories must be true; composites are marked as composite. Never invent metrics.
• Every code block runs on the stated version.
• End on what the reader can do, not on a summary of what you did.
• Cast: always Jack (the path with friction) and Jill (the path that works) — see ../personas.md.
• Reminders: story, own line per person · useful ending.
• Format: short paragraphs · lists and tables · diagram + “what to notice”.