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 Coverage: Important concepts, principles, and practices—none omitted
• 🔨 Practical Orientation: Readers can apply it immediately after reading—not just empty theory
• 📊 Structured Thinking: Clear information architecture; quickly locate the content you need

Writing Standards

1. Language Requirements

Conciseness Standard:

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

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

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

Prohibited Words List:

• ❌ "As is well known", "Everyone knows", "Obviously"
• ❌ "Very", "Extremely", "Exceedingly" (replace with specific data)
• ❌ "Let us", "Together", "Next" (go straight to the point)
• ❌ "May", "Perhaps", "Maybe" (deep-dives require certainty)
• ❌ "Here", "It should be noted 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 Structure:

标题: 清晰说明解决什么问题
├── 核心结论前置(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 the section
• Use subheadings to break down complex content
• Highlight key information with bold, code blocks, and lists

3. Knowledge 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 it exists / 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 with similar technologies

Extension Layer:

• Further Reading: Official documentation or authoritative resource links
• Version Information: Technology version requirements and compatibility

4. Code Example Standards

Code examples must:

• ✅ Be directly runnable (not pseudocode)
• ✅ Include key comments (explaining "why" rather than "what")
• ✅ Show a minimal usable example (no redundant code)
• ✅ Specify 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. Bullet 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: Distill the core knowledge points

Principles for extracting knowledge points:

• Use a mind map or outline to list all relevant knowledge points
• Mark importance: P0 (must) / 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 vague 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 the code comments necessary? Delete obvious comments
• Is there introductory filler? Consider going straight to the topic

Step 4: Optimize the structure

Information architecture optimization:

1. Conclusion first: Put the core viewpoint at the beginning of the paragraph/section
2. Progressive relationship: From simple to complex, from concept to practice
3. Modularization: Each section is independently complete and can be read on its own
4. Cross-reference: Provide jump links for related content

Step 5: Quality check

Pre-publish checklist:

Content completeness:

• Core concepts all have clear definitions
• Every important knowledge point has an example
• Code examples are all runnable
• Include 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 characters)

Title writing formula

Characteristics of titles for practical articles:Functionality > attractiveness

Recommended formats:

1. Problem-solving type:

   • "3 ways to solve problem X"
   • "How to optimize X performance"
   • "The complete solution to X error"

2. Knowledge-teaching type:

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

3. Practice Guide Type:

   • "X Best Practices Guide"
   • "X from Beginner to Mastery"
   • "Complete Guide to Implementing X Functionality"

4. Comparative Analysis Type:

   • "X vs Y: Technology Selection Guide"
   • "Comparison of 5 Ways to Implement X"
   • "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

Special Scenario Handling

Scenario 1: Simplifying Complex Concepts

Strategy:

1. Analogy Method: Use Everyday Life Analogies for Technical Concepts
2. Decomposition Method: Break Down Complex Concepts into 3-5 Sub-concepts
3. Visualization: Use Charts or Flowcharts to Show Relationships

Example:

## 闭包原理

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

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

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

Scenario 2: Version Difference Explanation

Strategy:

• Clearly Indicate the Version Requirements for Each Feature
• Use Tables 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

Strategy:

• Provide Before-and-After Performance Data Comparison for Optimization
• Explain the Time/Space Complexity Impact of the Optimization
• Indicate 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
);
\```

Common Problem Handling

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, with References Used Afterwards

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?

Judgment Criteria:

• Decide Based on the Target Reader (Beginner/Intermediate/Advanced)
• Use Parenthetical Notes on First Appearance, Then Use Directly Afterwards
• For Concepts That Are Too Basic, 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)
• ✅ Annotate 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: Practice 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 Have Code Examples
• Code Examples Can Be Run Directly
• Version/Environment Requirements Are Indicated
• Includes Explanations of Common Pitfalls
• Provides Best Practice Suggestions

Concise Language

• Deleted All Modifiers Such as "very", "extremely", "quite"
• No Vague Expressions Such as "possibly", "perhaps"
• Each paragraph begins with the core conclusion
• A single sentence should not exceed 25 characters
• No repeated information

Clear structure

• The 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 executable 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. Use 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 cases: Get real-world problems from GitHub and Stack Overflow
4. Data-driven: Support opinions 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 terms without explaining them
• ❌ 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 showing off the author's literary talent. Conciseness, accuracy, and practicality are the only standards.