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

1. Never oversell:

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

1. 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