technical-blog-post

---
name: technical-blog-post
description: Write high-quality technical blog posts with strong structure and clarity. Use when asked to write a blog post, technical article, tutorial, or guide about programming, software, APIs, tools, or technical concepts. Triggers include "write a blog post about...", "create a technical article", "help me write about [technical topic]", or requests for tutorials and how-to guides.
---

# Technical Blog Post

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

## Structure

1. **Lead with the problem or value** - First paragraph answers "why should I read this?"
2. **Use scannable headings** - Readers skip around; let them
3. **Code examples**: minimal, complete, runnable
4. **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)