Technical Blog Writing Skill

Write technical blog posts that explain system internals, architecture, and implementation details.

When to Use

• Explaining system internals or implementation details
• Source code analysis and walkthrough
• Comparing different implementations or approaches
• Doc-driven architecture/comparison posts (no source code in scope)

Document Structure

# [Topic] Deep Dive

Brief intro + why it matters.
> **Code Version**: Based on [project] `vX.Y.Z` tag (or commit id for external repos).

## 1. Introduction (problem + scope)
## 2. Background / Prerequisites
## 3-N. Core Content (by data flow, not code structure)
## N+1. Comparison / Trade-offs
## N+2. Code Index (files, functions, line numbers)
## References

Key guidelines:

• Chapter 1 = Introduction + Navigation only, no implementation details
• Organize content by data flow, not by code components
• Use > ⏭️ If reading first time, skip to §X, return here when needed.

---

Core Principles

1. Progressive Explanation

• Start with the problem, not the solution
• Build concepts layer by layer
• Explain "why" not just "what"

2. Concept-First (概念前置)

• Never use undefined terms: Define before use
• Add concept sections: Create §X.Y.1 to introduce concepts before implementation
• Use navigation hints: > ⏭️ If unfamiliar with X, see §Y first

3. Big Picture First (整体图景优先)

• Start with unified visual overview before details
• Use comparison diagrams/tables for 2+ approaches
• Show complete flow in one diagram

4. Balanced Comparison

• Analyze BOTH sides; don't cherry-pick
• Use comparison tables for similar concepts
• Identify what's truly different vs. equivalent

5. Design Decision Explanation

• What problem does it solve?
• What alternatives exist?
• What trade-offs?

6. Concrete Examples

• 1-2 practical examples per major section
• Show input → process → output
• Use real data for abstract concepts (e.g., inverted index with actual words)

7. Terminology Accuracy

• Verify terms via source code or official docs
• Define domain-specific terms when introducing
• Don't assume terms are interchangeable

---

Research Strategy

Source Code Exploration (MUST for project-specific details)

• Specific code logic, conditions, data structures
• Configuration parameters and defaults
• File paths and line numbers for citations
• Implementation variants (e.g., Wide vs Compact)

Knowledge/Memory (OK for standard protocols)

• Standard syntax (ES DSL, HTTP, SQL)
• Well-known algorithms (B+ tree, inverted index)
• Public documentation content

Doc-Driven Research (when no source code)

1. Extract claim list (defaults, limitations, "supports X")
2. Find authoritative sources (official docs → vendor blogs → community)
3. Cite at claim location: （来源：[Label]）
4. Use reference-style links: [Label]: https://...
5. Separate fact vs inference
6. Never fabricate numbers

💡 Don't search source code for info not in the project. Focus on project-specific implementation.

---

Writing Guidelines

Code Examples

• Include file path and line numbers
• Explain what it does, not just show it
• Replace large blocks with flow diagrams + key snippets
• Add practical query/command examples

Diagrams (Prefer Mermaid)

Use colors to distinguish components:

flowchart LR
    A[Client] --> B[Component A] --> C[Component B]
    style A fill:#e1f5fe,stroke:#01579b
    style B fill:#fff3e0,stroke:#e65100
    style C fill:#e8f5e9,stroke:#2e7d32

Color scheme:

• 🔵 Blue (#e1f5fe): Client/Entry points
• 🟠 Orange (#fff3e0): Processing components
• 🟢 Green (#e8f5e9): Data/Storage
• 🔴 Pink (#fce4ec): Distributed execution

Add step numbers for complex flows:

flowchart LR
    A -->|1. Request| B -->|2. Parse| C -->|3. Execute| D -->|4. Return| A

Tables

• Use for comparisons, performance data, component summaries

Callouts

• 💡 Key Point: Critical insights
• ⚠️ Gotcha: Common mistakes
• 📝 Terminology: Definitions
• ⏭️ Navigation: Cross-references

---

Hybrid Architecture Documentation

When documenting systems combining multiple technologies (e.g., ES + ClickHouse, Java + C++):

1. Clarify Component Responsibilities

• Don't assume: Each component's role may differ from standalone usage
• Verify: Which handles metadata? Query parsing? Distributed execution?
• Document boundaries: Where does one end and another begin?

Example (TSearch = ES + ClickHouse):

• ES: Metadata management, DSL parsing, routing table
• ClickHouse: Data storage, distributed query execution
• ⚠️ Common mistake: Assuming RPC handles distributed execution

2. Communication Mechanism Evolution

• Document history: "Initially Thrift RPC, now migrating to JNI"
• Current state: Which interfaces use which mechanism?
• Why the change: Performance? Simplicity?

3. Data Flow Verification

Before writing, trace a

...