Technical Blog Post Outline

Turns a topic and raw notes into a tight blog post outline with a one-sentence thesis, a hook grounded in a real problem, and section-level evidence requirements.

License: CC0-1.0 · By waxmark · v1 · 2026-11-02

Share on X

Add a trust badge to your README

[![Waxmark](https://waxmark.app/api/badge/technical-blog-post-outline)](https://waxmark.app/items/technical-blog-post-outline/scan)
Report
Outline a technical blog post. Do not write the post; produce the skeleton a writer could draft from in one sitting, with every section's job and evidence already decided.

<topic>
{{TOPIC}}
</topic>

<notes>
{{NOTES}}
</notes>

<audience>
{{AUDIENCE}}
</audience>

<takeaway>
{{TAKEAWAY}}
</takeaway>

Target length: {{LENGTH_WORDS}} words (default 1,500 if empty). <notes> are the author's raw material: findings, code, numbers, war stories. <takeaway> is the one thing the reader should believe or be able to do afterward; if it is empty, propose one from <notes> and mark it `[proposed]`.

Rules:

1. Write a thesis first: one sentence that a reader could disagree with. "We cut p99 latency 60% by removing the cache" is a thesis; "Caching considerations" is not. Every section must advance the thesis or get cut.
2. Open with the reader's problem, not the author's journey. The hook is the concrete situation the <audience> recognizes from their own work, in 2-3 sentences. Save "how we got here" for a short context section if the thesis needs it.
3. Plan 4-7 sections. For each, specify: the claim it makes, the evidence from <notes> that supports it (quote or reference the specific note), the artifact it needs (code block, chart, table, diagram), and a word budget that sums to the target.
4. Where <notes> lack evidence for a claim the thesis needs, do not invent it. Mark the section `[needs evidence: ...]` with the specific measurement, example, or source the author must add.
5. Anticipate the three strongest objections an expert in <audience> would raise, and place each one in the section where it is best answered. A technical post that ignores obvious objections reads as marketing.
6. End with a section that gives the reader their next action, sized to the <takeaway>, and a one-line summary that could stand alone as a social post.

Use the audience's vocabulary. Prefer specific nouns and numbers from <notes> over category words.

## Output format

**Title options** - three titles: one plain-descriptive, one that leads with the result, one that leads with the surprising part. No clickbait.

**Thesis** - one sentence.

**Hook** - the 2-3 sentence opening, written out (this is the one part drafted in full).

**Outline** - numbered sections. Each as:
- `H2 heading`
- Claim: one sentence
- Evidence: specific items from <notes>, or `[needs evidence: ...]`
- Artifact: code / chart / table / diagram / none, with what it shows
- Objection handled: the objection, or "none"
- Words: budget

**Closing** - the next action for the reader (one sentence) and the standalone summary line.

**Cut list** - items from <notes> you left out and why, so the author knows it was deliberate.
Technical Blog Post Outline · Waxmark