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

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