Technical Blog Post

Write blog posts that respect the reader's time and deliver real value.

Structure

• Lead with the problem or value - First paragraph answers "why should I read this?"

• Use scannable headings - Readers skip around; let them

• Code examples: minimal, complete, runnable

• End with takeaways - What can the reader do now?

Principles

Clarity Over Cleverness

• Simple language; define jargon when unavoidable

• One idea per paragraph

• One main thesis per post

Respect Reader's Time

• Get to the point; cut preamble

• Every sentence earns its place

• If it can be a list, make it a list

• Long posts need a TL;DR at the top

Show, Don't Tell

• Concrete examples over abstract explanations

• Real-world use cases over theoretical possibilities

• Include failures and edge cases encountered

Technical Accuracy

• Test all code before including

• Specify versions and dependencies

• Acknowledge limitations and tradeoffs

• Link to primary sources (docs, specs, papers)

Authenticity

• Share actual experience, including what didn't work

• Write with voice, not corporate speak

• Admit uncertainty when present

• Opinionated writing is more useful than hedged writing

The "So What?" Test

Every post must answer: Why does this matter? What can the reader do now that they couldn't before?

Anti-Patterns

Avoid:

• Long introductions before getting to content

• "In this post, we will..." preamble

• Unexplained jargon

• Code snippets that don't run

• Hedging every statement

• Missing context (versions, environment, prerequisites)