Blog Writing Specialist

Blog Writing Specialist

Comprehensive blog writing combining technical depth, personal voice transformation, and AEO optimization.

Quick Decision Tree

---

Part 1: Technical Blog Writing

Write developer-focused technical blog posts.

Post Types

1. Tutorial / How-To

Step-by-step instruction. Reader should build something.

Structure:
1. What we're building (with screenshot/demo)
2. Prerequisites
3. Step 1: Setup
4. Step 2: Core implementation
5. Step 3: ...
6. Complete code (GitHub link)
7. Next steps / extensions

2. Deep Dive / Explainer

Explains a concept, technology, or architecture decision in depth.

Structure:
1. What is [concept] and why should you care?
2. How it works (simplified mental model)
3. How it works (detailed mechanics)
4. Real-world example
5. Trade-offs and when NOT to use it
6. Further reading

3. Postmortem / Incident Report

Describes what went wrong, why, and what was fixed.

Structure:
1. Summary (what happened, impact, duration)
2. Timeline of events
3. Root cause analysis
4. Fix implemented
5. What we're doing to prevent recurrence
6. Lessons learned

4. Benchmark / Comparison

Data-driven comparison of tools, approaches, or architectures.

Structure:
1. What we compared and why
2. Methodology (so results are reproducible)
3. Results with charts/tables
4. Analysis (what the numbers mean)
5. Recommendation (with caveats)
6. Raw data / reproducibility instructions

5. Architecture / System Design

Explains how a system is built and why decisions were made.

Structure:
1. Problem we needed to solve
2. Constraints and requirements
3. Options considered
4. Architecture chosen (with diagram)
5. Trade-offs we accepted
6. Results and lessons

Writing Rules for Developers

Voice and Tone

What Developers Hate

❌ "In today's fast-paced world of technology..." (filler)
❌ "As we all know..." (if we all know, why writing it?)
❌ "Simply do X" (nothing is simple if reading a tutorial)
❌ "It's easy to..." (dismissive of reader's experience)
❌ "Obviously..." (if obvious, don't write it)
❌ Marketing language in technical content
❌ Burying the lede under 3 paragraphs of context

Code Examples

Explanation Depth

State your assumed audience level explicitly at the start.

Blog Post Structure

The Ideal Structure

# Title (contains primary keyword, states outcome)

[Hero image or diagram]

**TL;DR:** [2-3 sentence summary with key takeaway]

## The Problem / Why This Matters
[Set up why the reader should care — specific, not generic]

## The Solution / How We Did It
[Core content — code, architecture, explanation]

### Step 1: [First thing]
[Explanation + code + output]

### Step 2: [Second thing]
[Explanation + code + output]

## Results
[Numbers, benchmarks, outcomes — be specific]

## Trade-offs and Limitations
[Honest about downsides — builds trust]

## Conclusion
[Key takeaway + what to do next]

## Further Reading
[3-5 relevant links]

Word Count by Type

---

Part 2: Brain Dump → Polished Post (Nick Nisi Voice)

Transform unstructured brain dumps into polished blog posts.

Process

1. Receive the Brain Dump

Accept whatever provided:

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

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

2. Read Voice and Tone

Load references/voice-tone.md to understand Nick's writing style.

Key characteristics:

• Conversational yet substantive
• Vulnerable and authentic
• Journey-based narrative
• Mix of short and long sentences
• Specific examples and real details
• Self-aware humor

3. Check for Story Potential

Read references/story-circle.md to understand the narrative framework.

Determine if content fits a story structure:

• Is there a journey from one understanding to another?
• Can you identify a problem and resolution?
• Does it follow: comfort → disruption → return changed?

4. Organize Content

Structure material into sections:

Common structures:

• Problem/experience → Journey → Results → Lessons
• Setup → Challenge → Discovery → Application
• Philosophy → How-to → Reflection
• Current state → Past → Learning → Future

5. Write in Nick's Voice

Opening:

• Hook with current position or recent event
• Set up tension or question
• Be direct and honest

Body:

• Vary paragraph length
• Use short paragraphs for emphasis
• Include specific details (tool names, commands, numbers)
• Show vulnerability where appropriate
• Use inline code formatting naturally
• Break up text with headers

Technical content:

• Assume reader knowledge but explain when needed
• Show actual commands and examples
• Be honest about limitations
• Use casual tool references

Ending:

• Tie back to opening
• Forward-looking perspective
• Actionable advice
• Optimistic or thought-provoking

---

Part 3: Jarad's Voice

Personal blog writing with distinctive voice.

Core Voice Patterns

Sentence Structure:

• Productive rambling: longer, winding sentences that add layers of context
• Preemptively address skeptics mid-thought with fourth-wall breaks
• Add specific technical context even when making broad claims
• Example: "...ok if you're gonna obsess over the accuracy of my estimate, I'll use t-shirt sizes instead of hours/weeks - i'm well aware of the lack of meaningful estimates in both pre- and post-agentic era - but what i'm saying is there is an undeniably amazing almost supernatural improvement..."

Concrete Over Abstract:

• Use specific actions: "trawled GitHub every morning" NOT "pushed boundaries"
• Use specific tools/people: "Matt Wolfe, MattVidPro, Claude" NOT "popular YouTubers"
• Use vivid personal analogies: "boss staring at you while you work" NOT "incubation phase"
• Show insider knowledge: "GitHub pulse > YouTube hype"

Tone Elements:

• Direct, almost confrontational: "Use your brain and curate them yourself"
• Data-focused even in failure: "Data is data"
• Dark self-interest angle: "stashing dynamite in our doomsday bunkers"
• Self-aware about exaggeration: acknowledge imprecision before critics do

NEVER Use:

• "This isn't X, it's Y" profound-sounding structures
• Cliché transitions: "here's the kicker", "here's where it gets interesting"
• Abstract action verbs without details: "experimented relentlessly", "pushed boundaries"
• Overly polished blog-speak
• Clean, explanatory metaphors like "incubation phase"

Header Style:

• Minimalistic: 2-4 words maximum
• When read in sequence, headers tell their own story
• No explanatory subtitles
• Example progression: "Flat Charts" → "The Lab" → "Spring 2024" → "The Numbers" → "The Window"

Content Strategy

Opening:

• Address the skeptic's question directly
• Don't try to be clever - just state what they said

Body:

• Share concrete personal experiences with specific details
• Break fourth wall to preempt criticism
• Name tools, people, communities to show you're in the trenches
• Let sentences run long when adding nuance
• Bury practical tips in the rambling

Addressing Critics:

• Do it mid-paragraph, not in separate defensive sections
• Use self-deprecating acknowledgment before they can attack
• Then pivot to the actual point

Closing:

• Direct callback to opening question
• Honest about self-interest and the dark future
• End with something that feels human and imperfect

Examples

Bad: "The shovelware isn't missing. It's incubating." Good: "I would say this is more accurately 'an incubation phase'. Side effects include tons of garbage code, extra long cycles devoted to theory - stuff that's usually in textbooks - except we didn't write them yet."

Bad: "I was hitting these incredible 'a-ha' moments weekly." Good: "I was on a roll, building stuff day and night - literally, as in I didn't sleep much anymore."

Bad: "Experimented relentlessly. Pushed boundaries. Tried to break things." Good: "While everyone was busy making fun of claude's shitty sense of humor, I looked at every single failure as progress. Data is data. When everyone was eating up the tools they saw Matt Wolfe or MattVidPro talk about, I just cast my line into the github sea every morning and got a pulse on the community - guess what - there are SO many more quiet non-youtube developers out there making tools at 10x speed than can be reported. Use your brain and curate them yourself."

---

Part 4: Category-Aware AEO System (Lightfast)

Create category-aware, AEO-optimized blog posts.

Critical: Accuracy Over Marketing

Before writing anything:

1. Verify every claim:

• If you cite a number, confirm the source
• If you mention a feature, confirm it exists in production
• When uncertain, ask for clarification

2. Never oversell:

• Disclose limitations: "Currently supports X; Y coming in vZ"
• Be honest about beta status and rollout timelines

3. Match category voice:

• Technology: Technical authority, data-driven
• Company: Visionary, category-defining
• Product: Problem-solver, benefit-oriented

Category Selection

Writing Guidelines

1. Concise & scannable: Match category word counts 2. Lead with value: Start with what readers gain 3. Be transparent: Mention beta status, limitations 4. Active voice: "You can now..." not "Users are able to..." 5. No emoji: Professional tone 6. Include TL;DR: 80-100 words for AI citation 7. FAQ section: 3-5 questions matching search queries 8. Code examples: Required for Technology posts

Required Frontmatter

Every draft MUST include:

• title, slug, publishedAt, category (core)
• excerpt, tldr (AEO)
• seo.metaDescription, seo.focusKeyword (SEO)
• _internal.status, _internal.generated (traceability)

---

Part 5: Diagram Generation

When to Use Diagrams

For architecture diagrams and benchmark visualizations:

Use diagramming tools (Mermaid, Excalidraw, draw.io) for architecture diagrams and charting libraries (matplotlib, Chart.js) for benchmark visualizations. These tools provide better control, are self-hosted, and avoid third-party execution risks.

---

Part 6: Distribution

Where Developers Read

---

Common Mistakes

---

Bundled Resources

References

• references/voice-tone.md - Complete Nick Nisi voice and tone guide
• references/story-circle.md - Story Circle narrative framework

Usage

Load reference files when writing in specific voices:

• Nick Nisi voice → read references/voice-tone.md + references/story-circle.md
• Jarad voice → use Part 3 guidelines
• Technical writing → use Part 1 & 2
• Category-aware → use Part 4

Tech Talk Story Circle Framework

The Story Circle is an eight-step framework adapted from Dan Harmon's storytelling technique. It structures tech talks to create engaging narratives.

The Eight Steps

1. Introduction (You)

Top half - Order

Introduce yourself and the current status quo of your project.

• Set the scene with the existing workflow or technology stack
• Establish the baseline before disruption
• Make the audience understand the familiar ground

2. Problem Statement (Need)

Top half - Order

Identify and explain the problem you're trying to solve.

• Clearly articulate what's not working
• Help the audience feel the pain point
• Create the motivation for change

3. Exploration (Go)

Crossing to bottom half - Chaos

Describe the steps taken to address the problem.

• What did you try?
• What worked?
• What didn't work?
• Show the journey into the unknown

4. Experimentation (Search)

Bottom half - Chaos

Detail the process of digging into the actual problem.

• What did you learn?
• What experiments did you run?
• What discoveries did you make?
• Share the messy middle of problem-solving

5. Solution (Find)

Bottom half - Chaos

Explain how you found the solution or made progress.

• Present the breakthrough moment
• Show what finally clicked
• Explain the technical approach that worked

6. Challenges (Take)

Bottom half - Chaos

Discuss the actual implementation of the project.

• Emphasize the disruption to the status quo
• Share the difficulties and tradeoffs
• Be honest about the cost of change

7. Apply Knowledge (Return)

Crossing to top half - Order

Describe the results and how the solution was integrated.

• Show how you brought the solution back to your project
• Demonstrate the practical application
• Return to the familiar with new tools

8. Results & Insights (Change)

Top half - Order

Conclude with lessons learned and how things changed.

• Share metrics or outcomes
• Explain what changed in your workflow or perspective
• Leave the audience with actionable insights

Structure Notes

Top half (steps 1, 2, 7, 8): Represents established practices and order Bottom half (steps 3, 4, 5, 6): Represents disruption and experimentation

The character (you) starts in the top half, enters the bottom half to experiment and disrupt, then returns to the top half with new knowledge, changing the status quo.

Example

From "Unleashing the TypeScript Compiler":

1. Status quo of a TypeScript/React project using Material-UI 2. Challenges faced with the project 3. Solutions tried to work around issues 4. Exploring the TypeScript compiler and codemods 5. Using new knowledge to solve problems 6. Challenges implementing the solution for every scenario 7. Applying knowledge to the project 8. Results and changed team perspective on codemods

Nick Nisi's Voice and Tone

Captured from analyzing posts at nicknisi.com

Core Writing Characteristics

Voice

Personal, authentic, conversational yet thoughtful. Nick writes like he's having a one-on-one conversation with a peer developer over coffee.

Vulnerability

Nick isn't afraid to admit uncertainty, fear, or being wrong. He shares his journey from skepticism to understanding.

Examples:

• "I was wrong, but not in the way I feared."
• "I won't lie – joining Meta was intimidating."
• "That night in my hotel room, I couldn't sleep."
• "Looking at my interviewers' backgrounds... it was hard not to feel like an outsider."

Narrative Structure

Posts often follow a journey: initial position → experience/challenge → realization → new understanding. He builds tension and resolves it.

Sentence Style

• Mix of short punchy sentences and longer explanatory ones
• Uses fragments for emphasis
• Varies paragraph length for rhythm
• Short paragraphs for key moments: "🤯" stands alone, "That changed everything." gets its own paragraph

Specific Phrases and Patterns

Opening hooks:

• Sets up expectations then challenges them
• Often starts with current position or recent event
• "I've been thinking a lot about..."
• "Want to dive in? [Links]" (practical calls to action upfront)

Transitions:

• "Here's what I've learned..."
• "The strange part?"
• "Let's talk about..."
• "But beneath the apprehension..."

Emphasis techniques:

• Single-line paragraphs for impact
• Emojis used sparingly but effectively (🤯, 😂)
• Italics for internal thoughts or emphasis
• Bold for key concepts

Metaphors and analogies:

• Technical concepts explained through relatable comparisons
• "Like cooking with your eyes closed"
• "The developers who insist on writing every line by hand are like accountants refusing to use spreadsheets"
• "It was a pair programmer who spoke fluent bash"

Technical Writing Style

Code and tools:

• Mentions specific tools naturally (vim, tmux, rg, npm)
• Shows actual commands and code when relevant
• Explains technical decisions without over-explaining
• Assumes reader has technical knowledge but explains when needed

Examples:

• Inline code formatting: CLAUDE.md, git, npm test
• Commands shown naturally in prose
• Tool names used casually: "I watched it use rg to search through codebases"

Honesty About Limitations

Nick admits when things aren't perfect:

• "The PRs it generated weren't perfect. But they worked. Somewhat."
• "Would I ship our vibe-coded GitHub Action to production? No way."
• "Not perfect, not production-ready, but working."

Self-Awareness and Humor

Light self-deprecation and humor:

• "(except maybe 'Why doesn't Nick use VS Code?' 😉)"
• "One of my favorite memories? Getting texts from friends asking why my face kept showing up in their Instagram feeds."
• "I like to think I brought a certain… charm to people's social media experience."
• Acknowledging his tooling preferences with humor

Structure Patterns

Sections often use:

• Clear headers that are descriptive
• Lists with explanations
• Tables when comparing options
• Code examples with context
• Pull quotes or emphasized text

Common section patterns:

• The Setup/Problem → The Journey → The Results → Lessons Learned
• Philosophy sections: "Here's what I've learned..."
• How-to sections with practical steps
• Reflection sections: "Looking back..."

Conclusions

Endings often:

• Tie back to opening tension or question
• Offer forward-looking perspective
• Include actionable advice
• End on optimistic or thought-provoking note

Examples:

• "The party isn't over – we're just changing the runtime!"
• "That week, I learned to code with my eyes wide shut. The strange part? I've never seen more clearly where we're headed."
• "You're not being replaced; you're being amplified."

Authenticity Markers

Real examples:

• Specific projects and PRs with links
• Actual teammates mentioned by name
• Real events (MCP Night, onsite meetings)
• Concrete details (5,000 lines of TypeScript, two hours, 600 developers)

Acknowledges help:

• "Thanks to John Christopher for reviewing this post."
• Credits teammates and collaborators

Tone Shifts

Nick modulates tone based on content:

• Technical tutorials: Clear, instructional, still conversational
• Personal reflections: Vulnerable, thoughtful
• Tool reviews: Enthusiastic but honest
• Career stories: Reflective, self-aware

What to Avoid

• Corporate speak or marketing language
• Overly formal academic tone
• Pretending to have all the answers
• Dismissing reader concerns
• Being preachy or condescending
• Hiding uncertainty or mistakes

Key Principles

1. Be conversational but substantive 2. Share the journey, not just the destination 3. Admit when you're uncertain or learning 4. Use specific details and real examples 5. Balance technical depth with accessibility 6. End with forward momentum 7. Write for a peer, not a student 8. Show vulnerability builds credibility 9. Humor works when it's self-aware 10. Practical value matters