# name: writing-blog-posts description: Writes technical blog posts built on one specific claim, a three-sentence hook, and real code, numbers, and failures. Use when the user asks to write a blog post, an engineering blog article, a technical write-up of a project or incident, or a dev.to/Medium-style post. Do not use for documentation, tutorials, or marketing landing-page copy — separate skills cover those.

# Writing Blog Posts

# When to use / when NOT to use

• Use for: technical blog posts, engineering write-ups, postmortem narratives for a public audience, "how we built X" articles.
• Do NOT use for: documentation (writing-technical-documentation), tutorials (writing-tutorials), API reference (writing-api-documentation), or landing-page copy (frontend-skills/creating-landing-pages).

# House rules

1. One idea per post, stated as a specific claim in the title.

   • ✅ "We cut our CI bill 60% by deleting half our integration tests"
   • ❌ "Thoughts on testing"

2. Hook in the first 3 sentences — the problem, a surprising fact, or the result. No throat-clearing.

   • ✅ "Our CI bill hit $40k/month. The fix wasn't caching or bigger runners — it was deleting 4,000 tests. Here's how we decided which ones."
   • ❌ "Testing is a very important topic in software engineering. In this post, I will share some thoughts…"

3. Real code, real numbers, real failures. Specifics earn trust; sanitize secrets, keep the mess.

   • ✅ "The first attempt shaved 4% — nowhere near worth the two weeks it took."
   • ❌ "After some optimization, performance improved significantly."

4. Subheadings tell the story alone. A skimmer reading only headings gets the arc.

   • ✅ "The $40k bill → What the tests actually covered → Deleting with a safety net → Results after 90 days"
   • ❌ "Introduction → Background → Discussion → Conclusion"

5. Personal experience over generic advice. "We did X and Y happened" beats "you should X".

   • ✅ "We tried contract tests first; they caught 2 of the 17 regressions."
   • ❌ "Consider using contract tests, which can catch regressions."

6. Honest limitations section — where this wouldn't work, what you'd do differently.

   • ✅ "This only worked because our unit coverage was already strong; with flaky units, deleting integration tests would be reckless."
   • ❌ Presenting the approach as universal.

7. At most one call-to-action, at the end.

   • ✅ One "we're hiring" or one "try the tool" link.
   • ❌ Newsletter box, three product links, and a webinar pitch mid-article.

# Workflow

1. Write the claim as one sentence; if it needs "and", split into two posts.
2. Collect the evidence: numbers, code snippets, timelines, failed attempts. No evidence → no post yet.
3. Outline as story-telling subheadings (rule 4); check the headings alone carry the arc.
4. Draft: hook first (rule 2), then the story, then limitations, then the single CTA.
5. Self-review pass: delete every sentence that could appear unchanged in anyone else's post on the topic; verify every number has a source; confirm exactly one CTA. Fix and re-check.

# Edge cases

• No hard numbers available → use concrete qualitative specifics (timeline, error messages, before/after code); never invent or round up.
• Company-sensitive details → replace absolute revenue-like numbers with ratios/percentages, and say you did.
• Post is really a tutorial in disguise (reader follows steps) → switch to writing-tutorials.

# References

Extended before/after examples: see references/examples.md.