baphled/dotopencode/blog-writing

Skill: blog-writing

What I do

I provide expertise in crafting engaging technical blog posts and thought leadership pieces. I focus on narrative structure, audience calibration, and the seamless integration of code examples to make complex technical topics accessible and interesting.

When to use me

• Drafting technical tutorials or "how-to" guides for a blog
• Writing thought leadership articles about industry trends or architectural decisions
• Explaining complex features or updates to a broad developer audience
• Repurposing technical documentation into engaging long-form content

Core principles

1. Audience Calibration — Understand the reader's technical level and adjust the depth and jargon accordingly.
2. Narrative Arc — Every post should have a clear beginning (problem), middle (solution), and end (conclusion/next steps).
3. Code-Text Balance — Use code to illustrate points, but ensure the surrounding text explains the "why" and "how" clearly.
4. Skimmability — Use descriptive headings, bullet points, and bold text to make the content easy to scan.
5. Engagement — Use a conversational but professional tone, and include a clear call to action (CTA).

Patterns & examples

Technical Post Structure

• Headline: Catchy but descriptive (e.g., "Solving Race Conditions in Go").
• Introduction: Hook the reader, define the problem, and state what they'll learn.
• The Meat: Break the solution into logical sections with subheadings.
• Code Integration: Use small, focused snippets rather than giant blocks.
• Conclusion: Summarise key takeaways and provide a "what's next".

Code Example Pattern

"While the previous approach works for small datasets, it fails under load. Here's how to implement a more efficient worker pool:"

// Focus on the specific change, omit boilerplate
func startWorkerPool(count int) {
    for i := 0; i < count; i++ {
        go worker()
    }
}

Anti-patterns to avoid

• ❌ The Wall of Code — Large blocks of code without enough explanatory text.
• ❌ Undefined Jargon — Using acronyms or complex terms without a brief explanation.
• ❌ Clickbait Headlines — Titles that don't reflect the actual content of the post.
• ❌ Ignoring SEO — Failing to include relevant keywords and meta descriptions.

KB Reference

~/vaults/baphled/3. Resources/Knowledge Base/AI Development System/Skills/Communication-Writing/Blog Writing.md

Related skills

• tutorial-writing — For step-by-step technical guides.
• writing-style — To establish a consistent voice.
• proof-reader — For final clarity and correctness checks.
• documentation-writing — For foundational technical accuracy.