Developer Blog Writer

Transform unstructured thoughts into polished technical blog posts.

Reference Files

Load these before writing:

Process

1. Receive the Brain Dump

Accept whatever is provided:

• Scattered thoughts and ideas
• Technical points to cover
• Code snippets or commands
• Links to reference
• Conclusions or takeaways
• Random observations

Don't require organization. The mess is the input.

2. Load Voice Guide

Read references/voice-tone.md to understand the writing style:

• Professional-casual tone
• First-person, inclusive language ("we", "us")
• Technical-educator with peer credibility
• Show the journey, not just the destination

3. Identify Post Type & Template

Determine which type fits the content:

4. Check for Story Potential

Read references/story-circle.md and look for narrative opportunities:

• Is there a journey from confusion to clarity?
• A problem you solved?
• Something you learned the hard way?
• A perspective shift?

Not every post needs full Story Circle, but look for:

• Status quo → Disruption → New understanding
• "I thought X, then learned Y"

5. Organize & Write

Opening:

• Hook with a problem, question, or personal motivation
• No "In this post, I will..." - just start
• Set up tension or curiosity

Body:

• Vary paragraph length (short for emphasis)
• Include specific details (tool names, commands, versions)
• Show actual code, not just describe it
• Be honest about what didn't work
• Use inclusive language ("This gives us...")

Technical content:

• Assume reader competence, explain when needed
• Show real commands and outputs
• Acknowledge limitations and trade-offs

Ending:

• Tie back to opening
• Actionable takeaway
• Forward-looking ("Stay tuned for...")

6. Review & Optimize

Voice check:

• Does it sound like a developer talking to peers?
• Is there a clear thread from start to finish?
• Does it show the journey, not just the destination?

SEO check (from references/seo-checklist.md):

• Primary keyword in title and first paragraph
• Meta description (150-160 chars)
• URL slug is short and clean
• 2-3 internal/external links
• All images have alt text
• Code blocks specify language

Quick Voice Reference

Do:

• Write like explaining to a smart colleague
• Admit uncertainty or mistakes
• Use specific examples with real details
• Include actual code naturally
• Show what you tried, not just what worked
• Use "we" and "us" to include the reader

Don't:

• Use corporate or marketing speak
• Over-explain basic concepts
• Hide mistakes or pretend you knew all along
• Start with "In this post..." or "As we all know..."
• Force humor or excessive emojis

Example Patterns

Opening hooks:

I recently made the decision to revamp my portfolio...

`npm install` took 47 seconds. That felt wrong.

Showing the journey:

My first attempt was embarrassingly naive.

Then something clicked.

Technical details:

The fix was one line: `"moduleResolution": "bundler"` in tsconfig.

Conclusions:

The tool doesn't matter. The workflow does.

Workflow Example

Brain dump:

switched from npm to pnpm
- npm was slow, 45 seconds for install
- tried pnpm, now 8 seconds
- symlinks instead of copying
- had to update CI scripts
- one gotcha: peer deps behave differently
- conclusion: worth the switch for any project over 50 deps

Process:

1. Load voice-tone.md
2. Post type: Opinion/Perspective → load template
3. Check story-circle: Yes, pain point → discovery → results
4. Write with hook (speed comparison)
5. Show actual commands and timing
6. Include the CI gotcha (honesty about friction)
7. Run SEO checklist before publishing

Write posts you'd want to read. Technical depth, honest journey, clear takeaway.