# Examples — Blog Post House Style ## Contents - Complete worked example: opening (bad → house style) - Title pairs - Subheading arcs - Limitations sections - Gotchas ## Complete worked example: opening **❌ Before:** ```markdown # Some Thoughts on Database Migrations Database migrations are one of the most important yet often overlooked aspects of modern software development. Every developer will eventually need to deal with them. In today's fast-paced world, it's crucial to have a robust migration strategy. In this post, I will share some thoughts and best practices that I have learned over the years. ``` (Four sentences in: no claim, no evidence, nothing the reader can't predict.) **✅ After (house style):** ```markdown # A 40-character migration took our API down for 11 minutes The migration was one line: `ALTER TABLE orders ADD COLUMN note text`. It locked 90 million rows on our primary at 14:02 on a Tuesday. This post reconstructs the incident minute by minute, and shows the expand-migrate-contract pattern we now enforce in CI so it can't recur. ## 14:02 — the deploy that looked harmless ... ``` What changed: title is a specific claim with numbers; hook is the problem + the surprise in three sentences; timeline promises evidence, not opinions. ## Title pairs - ✅ "Keyset pagination made our deep pages 200× faster" / ❌ "Pagination best practices" - ✅ "We replaced 14 microservices with a monolith and cut p99 by half" / ❌ "Microservices vs monoliths" - ✅ "Everything we learned fuzzing our YAML parser for 30 days" / ❌ "An introduction to fuzzing" ## Subheading arcs ✅ Story alone in headings: ``` The bill nobody questioned What 4,000 integration tests actually tested The deletion protocol: score, quarantine, delete What broke (two things) and what didn't (everything else) 90 days later: numbers Where this would have gone wrong ``` ❌ Template headings: `Introduction / Background / Approach / Results / Conclusion` — interchangeable with any post ever written. ## Limitations sections ✅ "This worked because (1) unit coverage was 85%+ before we started, (2) our services share one language, so contract drift is rare, and (3) we could tolerate a staging-only canary for two weeks. Team with a polyglot stack or thin unit coverage: the quarantine step alone is still worth stealing; the mass deletion is not." ❌ "Of course, your mileage may vary." (says nothing) ## Hook patterns (three that work) - **The problem:** "Our CI bill hit $40k/month and nobody could say why." - **The surprising fact:** "Deleting tests made our deploys safer. Here's the data." - **The result:** "p99 went from 840 ms to 210 ms with a one-line change — after three weeks of wrong turns. The wrong turns are the useful part." All three commit to specifics in sentence one; none begin with the topic's importance. ## Gotchas - **The generic-sentence test is brutal but works:** if a sentence could close any post on the topic ("testing is a journey, not a destination"), it adds nothing — delete it. - **Rounded-up numbers get called out** in comments ("60%" that's really 48% costs all credibility); use the real figure. - **Burying the result** to build suspense loses skimmers; the hook may reveal the ending — the story is *how*, not *whether*. - **Code screenshots** aren't searchable or copyable; always fenced blocks. - **Two ideas in one post** each get half the depth; the split versions both outperform the original.