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

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

Research Strategy

Source	When	Examples
Source code	Project-specific logic, defaults, file paths	Config params, implementation variants
Knowledge	Standard protocols, well-known algorithms	ES DSL, HTTP, B+ tree
Doc-driven	No source code; external systems	Official docs → vendor blogs → community

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

Role	Fill	Stroke	Text
Primary Actor	`#6C5CE7`	`#5A4BD1`	`#fff`
Core Component	`#0984E3`	`#0770C2`	`#fff`
Service / Hub	`#00B894`	`#009D7E`	`#fff`
Helper / Auxiliary	`#FDCB6E`	`#E0B050`	`#2D3436`
External / Remote	`#E17055`	`#C0392B`	`#fff`
Data Store	`#636E72`	`#2D3436`	`#fff`
Output / Sink	`#55EFC4`	`#00B894`	`#2D3436`
Light Accent	`#74B9FF`	`#0984E3`	`#2D3436`

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

Pitfall	Fix
Abrupt transitions	Connection sentences between sections
One-sided comparison	Comparison table, analyze both sides
Code without context	Explain role in the system
Too much source code	Diagram + key snippet
Undefined concepts	Concept section before use
Missing big picture	Unified visual overview first
Fabricated data	Qualitative language or cite source
Missing commit id	Always specify for external repos
Monotone diagrams	Full Mermaid styling standard

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

tech-blog