Technical Blog Writing Skill

When to Use

• Source code analysis / architecture deep dive
• Implementation walkthrough with file:line citations
• Technology comparison or design trade-off post
• Doc-driven research post (no source code in scope)

Document Skeleton

# [Topic] Deep Dive

Brief intro + why it matters.
> **Code Version**: Based on [project] `vX.Y.Z` (commit `abc1234`).

## 1. Introduction (problem + scope + navigation table)
## 2-N. Core Content (by data flow, not code structure)
## N+1. Design Decisions & Trade-offs
## N+2. Code Index (file, lines, responsibility)
## References

• §1 = problem + scope + navigation only — no implementation
• Each core section follows: concept → diagram → code → insight
• Navigation hints: > ⏭️ First-time readers: skip to §X.

Core Principles

1. Problem-first, progressive — start with the problem; build concepts layer by layer; explain "why"
2. Concept-before-use — never use undefined terms; add §X.Y.1 concept sections; cross-ref with ⏭️
3. Big picture first — unified visual overview before details; comparison diagram/table for 2+ approaches
4. Balanced comparison — analyze both sides; comparison tables; identify real differences vs. equivalences
5. Design decisions — state the problem, alternatives, and trade-offs for every non-obvious choice
6. Concrete examples — 1-2 per major section; show input → process → output with real data
7. Terminology accuracy — verify via source code or official docs; define on first use

Research Strategy

Doc-driven rules: extract claim list → cite at claim location → reference-style links [Label]: URL → separate fact vs. inference → never fabricate numbers.

Writing Guidelines

Code Examples

• Every snippet needs file_path:line_number
• Explain what it does, not just show it
• Replace large blocks with diagram + key snippet

Mermaid Styling Standard

All diagrams must use rich color styling. Monotone = rejected.

Color Palette

graph / flowchart — every node styled; subgraphs: named ID + emoji label + colored bg

graph TB
    subgraph local["🖥️ Local"]
        A["Component A"]
        B["Component B"]
    end
    subgraph remote["📱 Remote"]
        C["Client"]
    end
    A --> B --> C
    style A fill:#0984E3,stroke:#0770C2,color:#fff,stroke-width:2px
    style B fill:#00B894,stroke:#009D7E,color:#fff,stroke-width:2px
    style C fill:#E17055,stroke:#C0392B,color:#fff,stroke-width:2px
    style local fill:#DFE6E9,stroke:#636E72,stroke-width:2px,color:#2D3436
    style remote fill:#FAD7D4,stroke:#E17055,stroke-width:2px,color:#2D3436

sequenceDiagram — box rgb() per layer + emoji participants

sequenceDiagram
    box rgb(232,245,253) CLI Side
        participant CLI as 🔧 CLI
    end
    box rgb(220,247,235) Hub Side
        participant Hub as 🌐 Hub
    end
    CLI->>Hub: request
    Hub-->>CLI: response

Box colors: CLI rgb(232,245,253) · Hub rgb(220,247,235) · Web rgb(255,235,238) · Agent rgb(237,231,246) · User rgb(255,243,224)

stateDiagram-v2 — classDef per category + class binding

stateDiagram-v2
    [*] --> Active
    Active --> Idle : timeout
    classDef activeStyle fill:#0984E3,color:#fff,stroke:#0770C2,stroke-width:2px
    classDef idleStyle fill:#6C5CE7,color:#fff,stroke:#5A4BD1,stroke-width:2px
    class Active activeStyle
    class Idle idleStyle

Rules: step numbers for complex flows (A -->|1. Do X| B) · emoji in labels · no unstyled diagrams

Callouts

• 💡 Key Point — critical insight
• ⚠️ Gotcha — common mistake or subtle trap
• 🤔 Think About — design reasoning or open question
• ⏭️ Navigation — cross-reference to another section

Quality Gates

• No fabricated data — qualitative OK ("fast compression"); quantitative needs citation
• DRY concepts — same concept in 3+ places → one authoritative section, others reference it
• Hybrid systems — verify which component does what; trace actual data flow; don't assume

Common Pitfalls

Large Documents (>500 lines)

Draft-first: [topic]-DRAFT.md → build → review → merge → delete draft.

Checklist

• Sections flow with transitions; summary-detail pattern
• Concepts introduced before use; ⏭️ navigation hints
• Code examples have file:line; 1-2 concrete examples per section
• No fabricated numbers; terminology verified against source
• Code version / commit id specified
• All Mermaid diagrams fully styled (palette + emoji + backgrounds)
• Comparison tables for similar concepts

Output

• Location: docs/, ai_docs/, or project folder
• Filename: [topic-name].md
• Language: match user preference