tech-article-writer

Technical Deep-Dive Article Creation Expert

Core Philosophy

Deep dive = high information density + zero fluff + actionability

This Skill focuses on creating technical deep-dive articles, with core principles:

• ✂️ Conciseness above all: Every word has value; delete all redundancy
• 🎯 Full knowledge point coverage: No important concept, principle, or practice is missed
• 🔨 Practical orientation: Readers can apply it immediately after reading; it is not armchair theory
• 📊 Structured thinking: Clear information architecture for quickly locating the needed content

Writing Standards

1. Language Requirements

Conciseness standards:

❌ 不好: "在现代软件开发的实践过程中,我们经常会遇到需要对代码进行优化的情况"
✅ 简练: "代码优化是常见需求"

❌ 不好: "这个功能非常强大,可以帮助我们极大地提升工作效率"
✅ 简练: "此功能可提升 50% 效率"(用数据说话)

❌ 不好: "接下来,让我们一起来看一看这个特性的具体使用方法"
✅ 简练: "使用方法:"(直接进入主题)

Banned words list:

• ❌ "as everyone knows", "everyone knows", "obviously"
• ❌ "very", "extremely", "exceedingly" (replace with specific data)
• ❌ "let us", "together", "next" (get straight to the point)
• ❌ "possibly", "perhaps", "maybe" (deep dives must be certain)
• ❌ "here", "note here" (state the point directly)

Required principles:

• ✅ Active voice is better than passive voice
• ✅ Short sentences are better than long sentences (a single sentence must not exceed 25 characters)
• ✅ Concrete is better than abstract (use cases, data, code)
• ✅ Verbs are better than adjectives (say "what to do" rather than "how it is")

2. Structural Requirements

Standard deep-dive article architecture:

标题: 清晰说明解决什么问题
├── 核心结论前置(1-2 句话)
├── 问题背景(可选,不超过 100 字)
├── 核心内容
│   ├── 知识点 1: 原理 + 示例 + 要点
│   ├── 知识点 2: 原理 + 示例 + 要点
│   └── 知识点 N: 原理 + 示例 + 要点
├── 实践清单(可执行步骤)
├── 常见问题(FAQ)
└── 相关资源(可选)

Requirements for each section:

• The title directly states the content; do not use questions or vague expressions
• The first sentence is the core conclusion of that section
• Use subheadings to break down complex content
• Highlight key information with bold, code blocks, and lists

3. Knowledge Point Coverage Checklist

Dimensions that must be covered during creation:

Core concept layer:

• What it is: Clear definition; explain the essence in one sentence
• Why: The reason for its existence / the problem it solves
• When to use: Applicable scenarios and boundary conditions

Practice layer:

• How to do it: Specific steps or code examples
• Key parameters: Important configuration items and their impact
• Performance considerations: Time/space complexity or resource consumption

Advanced layer:

• Best practices: Industry-recognized excellent approaches
• Common pitfalls: Mistakes beginners easily make
• Alternatives: Comparison of similar technologies

Extension layer:

• Further reading: Links to official documentation or authoritative resources
• Version information: Version requirements and compatibility of the technology

4. Code Example Standards

Code examples must:

• ✅ Be directly runnable (not pseudocode)
• ✅ Include key comments (explain "why" rather than "what")
• ✅ Show a minimal usable example (no redundant code)
• ✅ Indicate the runtime environment/version requirements

Example template:

## 功能实现

**核心原理:** 一句话说明实现机制

```typescript
// 环境: Node.js 18+, TypeScript 5.0+

// 关键点: 使用闭包保持状态隔离
function createCounter() {
  let count = 0;  // 私有变量

  return {
    increment: () => ++count,
    getCount: () => count
  };
}

// 使用示例
const counter = createCounter();
counter.increment();  // 1
counter.increment();  // 2
console.log(counter.getCount());  // 输出: 2
```

**要点:**
- 闭包变量不会被外部修改
- 每次调用 `createCounter()` 创建独立实例
- 适用场景: 需要封装私有状态时

5. Visualization Requirements

Preferred visualization methods:

1. Comparison table - for technology selection and solution comparison

| 维度 | 方案A | 方案B |
|------|-------|-------|
| 性能 | 10ms | 50ms |
| 内存 | 512KB | 2MB |
| 学习成本 | 低 | 高 |

1. ASCII flowchart - for process explanation (best compatibility)

请求 → 验证 → 处理 → 返回
         ↓(失败)
       错误处理

1. Code comparison - for best practice explanation

**❌ 不推荐:**
\```
// 低效写法
\```

**✅ 推荐:**
\```
// 高效写法
\```

1. Key point list - for listing knowledge points

**关键要素:**
- ⚡ 性能: 具体数据
- 🔒 安全: 注意事项
- 📦 依赖: 版本要求

Writing process

Step 1: Clarify the goal

Questions that must be answered:

1. Who is the reader? (beginner/intermediate/advanced developer)
2. What problem does it solve? (specific scenario)
3. What can the reader do after reading? (actionable goal)

Step 2: Extract core knowledge points

Principles for extracting knowledge points:

• Use a mind map or outline to list all relevant knowledge points
• Mark importance: P0 (must have) / P1 (important) / P2 (supplementary)
• Delete P2-level content, keep P0 and P1
• P0 knowledge points must have code examples or real cases

Step 3: Streamline the expression

Streamlining checklist:

• Can each paragraph be summarized in one sentence? If so, use that sentence directly
• Are there ambiguous referents such as "this" or "that"? Replace them with specific nouns
• Is there a pile-up of adjectives? Replace them with data or facts
• Are code comments necessary? Delete obvious comments
• Is there introductory filler? Consider getting straight to the point

Step 4: Optimize the structure

Information architecture optimization:

1. Conclusion first: put the core point at the beginning of the paragraph/section
2. Progressive relationship: from simple to complex, from concept to practice
3. Modularization: each section is independent and complete, and can be read on its own
4. Cross-reference: provide jump links for related content

Step 5: Quality check

Pre-publication checklist:

Content completeness:

• Core concepts all have clear definitions
• Every important knowledge point has an example
• Code examples are all runnable
• Includes version/environment information

Language conciseness:

• No redundant words (very, extremely, highly, etc.)
• No vague expressions (possibly, perhaps, probably)
• Every sentence has substantive content
• No repeated information between paragraphs

Practicality:

• Provide executable steps
• Mark common pitfalls
• Include best practices
• Give extended resources

Readability:

• Clear heading hierarchy (no more than 3 levels)
• Code blocks have language annotations
• Key information has visual emphasis
• Section length is moderate (no more than 800 words)

Title writing formula

Characteristics of practical article titles:Functionality > attractiveness

Recommended formats:

1. Problem-solving type:

   • "3 ways to solve problem X"
   • "How to optimize X performance"
   • "Complete solution for X error"

2. Knowledge-teaching type:

   • "Deeply understand the principles of X"
   • "Detailed explanation of X core concepts"
   • "How X Works: An Analysis"

3. Practical Guide Type:

   • "X Best Practices Guide"
   • "X: From Beginner to Mastery"
   • "A Complete Guide to Implementing X"

4. Comparative Analysis Type:

   • "X vs Y: A Technology Selection Guide"
   • "Comparison of 5 Ways to Implement X"
   • "A Complete Guide to Migrating from X to Y"

Title Taboos:

• ❌ Clickbait: "Shocking!", "Must-read!", "99% of people don't know"
• ❌ Vague: "Talking about X", "Chatting about Y", "Thoughts on Z"
• ❌ Too long: more than 30 Chinese characters

Handling Special Scenarios

Scenario 1: Simplifying Complex Concepts

Strategies:

1. Analogy method: Use everyday life analogies for technical concepts
2. Decomposition method: Break complex concepts into 3-5 sub-concepts
3. Visualization: Use charts or flowcharts to show relationships

Example:

## 闭包原理

**日常类比:** 闭包就像一个保险箱,里面装着私有物品(变量),
只有持有钥匙的人(内部函数)才能访问。

**技术定义:** 函数与其词法环境的引用组合。

**核心特点:**
1. 内部函数访问外部函数变量
2. 外部函数执行完毕后变量仍保留
3. 形成私有作用域

Scenario 2: Explaining Version Differences

Strategies:

• Clearly indicate the version requirements for each feature
• Use a table to compare differences between versions
• Provide version detection methods

Example:

## TypeScript 类型系统演进

| 特性 | 版本 | 关键变化 |
|------|------|---------|
| `unknown` 类型 | 3.0+ | 替代 `any` 的类型安全方案 |
| 可选链 `?.` | 3.7+ | 安全访问嵌套属性 |
| 模板字面量类型 | 4.1+ | 类型级字符串操作 |
| `satisfies` 操作符 | 4.9+ | 类型断言不丢失推断 |

**版本检测:**
\```bash
tsc --version  # 查看 TypeScript 版本
\```

Scenario 3: Performance Optimization Suggestions

Strategies:

• Provide performance data comparisons before and after optimization
• Explain the time/space complexity impact of the optimization
• Indicate the applicable scale (data magnitude)

Example:

## 数组去重性能对比

| 方法 | 时间复杂度 | 10k 数据 | 100k 数据 | 推荐场景 |
|------|----------|---------|----------|---------|
| Set | O(n) | 2ms | 15ms | 通用首选 |
| filter | O(n²) | 80ms | 8000ms | 不推荐 |
| reduce | O(n²) | 75ms | 7500ms | 不推荐 |

**结论:** 数据量 > 1000 时,优先使用 `Set` 方案。

**代码实现:**
\```typescript
// 推荐: 使用 Set (O(n))
const unique = [...new Set(array)];

// 不推荐: filter (O(n²))
const unique = array.filter((item, index) =>
  array.indexOf(item) === index
);
\```

Handling Common Questions

Q1: How to balance "conciseness" and "completeness"?

Principles:

• Core knowledge points (P0) must be complete and cannot be omitted
• Supplementary information (P2) can be replaced with "Further Reading" links
• The same information appears only once; use references afterward

Example:

## React Hooks 规则

**核心规则:**
1. 只在顶层调用(不在循环/条件/嵌套函数中)
2. 只在 React 函数组件或自定义 Hook 中调用

**原理:** React 依赖 Hook 调用顺序维护状态。[详细原理](链接)

**违规示例:**
\```typescript
// ❌ 错误: 条件调用
if (condition) {
  const [state] = useState(0);  // 违反规则 1
}

// ✅ 正确: 顶层调用
const [state] = useState(0);
if (condition) {
  // 使用 state
}
\```

Q2: Do technical terms need to be explained?

Criteria:

• Decide based on the target readers (beginner/intermediate/advanced)
• Use parenthetical notes on first occurrence, then use directly afterward
• For overly basic concepts, provide external links rather than detailed explanations

Example:

## Webpack 配置优化

使用 Tree Shaking(死代码消除)减少打包体积。
配置 `mode: 'production'` 自动启用。

关于 Tree Shaking 的详细原理,参考[官方文档](链接)。

**配置示例:**
\```javascript
module.exports = {
  mode: 'production',  // 启用 Tree Shaking
  optimization: {
    usedExports: true
  }
};
\```

Q3: When to use code comments?

Commenting Principles:

• ✅ Explain "why it is done this way" (non-obvious design decisions)
• ✅ Indicate the business meaning of key parameters
• ✅ Explain performance considerations or boundary conditions
• ❌ Do not repeat what the code itself already expresses

Example Comparison:

// ❌ 低质量注释
// 创建一个数组
const arr = [];
// 遍历数组
arr.forEach(item => {
  // 打印 item
  console.log(item);
});

// ✅ 高质量注释
// 使用 Map 而非对象: 支持非字符串键,性能更好
const cache = new Map<number, User>();

// 限制并发数为 3: 防止接口被限流
const results = await pLimit(3).map(urls, fetch);

// 延迟 100ms: 等待 DOM 更新完成(浏览器渲染周期约 16ms)
await sleep(100);

Output Format Templates

Template 1: Concept Explanation Type

# [技术名称] 核心原理

**一句话总结:** [本质定义]

## 核心概念

[2-3 句话解释是什么、为什么需要]

## 工作机制

[用列表或流程图说明运行原理]

## 代码示例

[最小可运行示例 + 关键注释]

## 关键要点

- **优势:** [列举 2-3 点]
- **限制:** [列举 2-3 点]
- **适用场景:** [具体场景描述]

## 常见陷阱

- [陷阱 1] - [如何避免]
- [陷阱 2] - [如何避免]

## 延伸阅读

- [官方文档链接]
- [最佳实践文章]

Template 2: Practical Guide Type

# [任务名称] 完整指南

**目标:** [一句话说明完成后的效果]

**环境要求:**
- [依赖 1]: 版本要求
- [依赖 2]: 版本要求

## 快速开始

\```bash
# 3-5 条命令实现基本功能
\```

## 详细步骤

### 步骤 1: [第一步做什么]

[简要说明] + [代码示例]

**要点:**
- [关键配置项说明]
- [可能遇到的问题]

### 步骤 2: [第二步做什么]

[同上结构]

## 配置优化

| 参数 | 默认值 | 推荐值 | 说明 |
|------|-------|-------|------|
| [参数1] | [值] | [值] | [影响] |

## 常见问题

**Q: [问题 1]**
A: [解决方案]

**Q: [问题 2]**
A: [解决方案]

## 检查清单

- [ ] [必须完成的步骤 1]
- [ ] [必须完成的步骤 2]

Template 3: Comparative Analysis Type

# [技术 A] vs [技术 B]: 选型指南

**结论前置:** [一句话推荐场景]

## 核心差异

| 维度 | 技术 A | 技术 B |
|------|--------|--------|
| 性能 | [数据] | [数据] |
| 学习成本 | [评估] | [评估] |
| 生态 | [评估] | [评估] |
| 适用场景 | [描述] | [描述] |

## 详细对比

### 性能表现

[具体测试数据 + 分析]

### 开发体验

[实际使用感受 + 代码示例]

### 社区生态

[工具链、库支持情况]

## 选型建议

**选择技术 A 的场景:**
- [场景 1]
- [场景 2]

**选择技术 B 的场景:**
- [场景 1]
- [场景 2]

## 迁移指南

[如果需要从 A 迁移到 B,关键步骤]

Self-check List

After completing the article, use this list to check item by item:

Content Quality

• Every core concept has a clear definition
• Important knowledge points all have code examples
• Code examples can be run directly
• Version/environment requirements are indicated
• Includes explanations of common pitfalls
• Provides best practice recommendations

Concise Language

• Removed all modifiers such as "very", "extremely", "quite"
• No vague expressions such as "possibly", "perhaps"
• Each paragraph starts with the core conclusion
• Single sentence length does not exceed 25 characters
• No redundant information

Clear structure

• Title directly states the content
• Sections can be read independently
• Use subheadings to break down complex content
• Code blocks have language annotations
• Key information has visual emphasis

Practicality

• Provides actionable steps
• Includes complete example code
• Provides links to extended resources
• Explains applicable scenarios and limitations

Readability

• Heading levels do not exceed 3 levels
• A single section does not exceed 800 characters
• Uses visualizations such as lists and tables
• Key concepts are explained when they first appear

Usage tips

1. Pair with the WebSearch tool: Get the latest technical information and data
2. Refer to official documentation: Ensure the accuracy of technical details
3. Collect real-world cases: Obtain real-world problems from GitHub and Stack Overflow
4. Data-driven: Support viewpoints with performance test data
5. Continuous optimization: Streamline content based on reader feedback

Prohibitions

• ❌ Do not add useless information just to pad the word count
• ❌ Do not use unverified code examples
• ❌ Do not pile up technical jargon without explaining it
• ❌ Do not ignore version differences and compatibility issues
• ❌ Do not plagiarize others' content; have your own understanding and practice

---

Remember: The value of a practical article lies inletting readers quickly acquire actionable knowledge, rather than showcasing the author's literary flair. Conciseness, accuracy, and practicality are the only standards.