technical-writer

技术写作

README 专属模式（主视觉、TL;DR、快速入门）请参阅 readme-craft 技能。

内容类型与写作指南

1. 概念说明

为抽象概念建立思维模型。

# [Concept Name]

## The Problem It Solves

[Concrete scenario where this matters - make the reader FEEL the pain]

## The Core Idea

[One paragraph, one analogy, zero jargon]

## How It Works

[Visual or step-by-step breakdown]

### Step 1: [First thing that happens]
### Step 2: [Next thing]
### Step 3: [Result]

## In Practice

[Code example with annotations]

## Common Misconceptions

- **Myth:** [What people wrongly believe]
- **Reality:** [What's actually true]

## When NOT to Use This

[Explicit boundaries - this builds trust]

开篇示例：

不佳：“依赖注入是一种设计模式，它……”
良好：“你的类需要一个数据库连接。你是在类内部创建它，还是从外部传入？这个选择决定了你的代码是可测试，还是会变成一场噩梦。”

**语气：**使用“这样做之所以有效，是因为……”，而不是“如你所见……”。使用“你可能会认为 X，但实际情况是 Y”，而不是“显然……”。绝不要使用“很简单”或“只需”（这些说法会轻视难度）。

2. 操作指南

让读者以最小阻力从 A 到达 B。

# How to [Accomplish Specific Goal]

**Time:** X minutes | **Difficulty:** Beginner/Intermediate/Advanced

## What You'll Build

[Screenshot or description of end result]

## Prerequisites

- [Specific tool/version]
- [Knowledge assumed]

## Steps

### 1. [Action verb] [Object]

[Why this step matters - one sentence]

```code
[Exact command or code]

预期结果：[他们应该看到什么]

2. [下一步操作]

[继续此模式]

验证是否有效

[测试命令或手动验证]

故障排除

[错误消息或症状]

原因：[发生原因] 修复：[确切解决方案]

后续步骤

• [相关指南]
• [进阶主题]

**Rules:** One action per step. Every step has expected output. Code is copy-paste ready.

### 3. Tutorial (Teaching Through Building)

Teach concepts by building something real.

```markdown
# Build [Something Concrete]

## What You'll Learn

By the end, you'll understand:
- [Concept 1]
- [Concept 2]
- [Concept 3]

## The Project

[Description of what we're building and why it's useful]

## Part 1: [Foundation]

### The Concept

[Brief explanation of the underlying idea]

### Implementing It

[Code with inline explanation]

### What Just Happened

[Reinforce the concept with what they just did]

## Part 2: [Build on Foundation]

[Repeat pattern, each part introducing one new concept]

## Recap

| Concept | Where We Used It |
|---------|------------------|
| [Concept 1] | Part 1 - [specific code] |
| [Concept 2] | Part 2 - [specific code] |

## Challenges

1. **[Easy extension]** - [Hint]
2. **[Medium extension]** - [Hint]
3. **[Hard extension]** - [Hint]

**规则：**每个章节只讲一个概念。构建真正可用的内容。展示错误及其修正。加入检查点以验证进度。

4. 深入解析 / 技术文章

面向希望精通主题的读者，进行全面探索。

# [Topic]: A Deep Dive

**Reading time:** X minutes | **Audience:** [Intermediate/Advanced] developers

## TL;DR

[3-5 bullet points covering the key insights]

## The Landscape

[Context: what exists, what problem space we're in]

## How [Thing] Actually Works

### Under the Hood

[Technical explanation with diagrams/code]

### The Tradeoffs

| Approach | Pros | Cons | Use When |
|----------|------|------|----------|
| A | | | |
| B | | | |

## Real-World Patterns

### Pattern 1: [Name]

[Code example from production-quality source]

## Common Pitfalls

### Pitfall 1: [Name]

**The mistake:**
```code
[Bad code]

修复方法：

[Good code]

原因：[说明]

延伸阅读

• [资源 1] - [涵盖内容]

## Code Examples

**Every code block needs:**
1. Context (what file, what situation)
2. Working code (not pseudocode unless explicitly stated)
3. Key lines highlighted or annotated

```python
# user_service.py - handling authentication

def authenticate(self, credentials):
    user = self.repository.find_by_email(credentials.email)
    if not user:
        return AuthResult.failure("User not found")  # <- Early return pattern

    if not user.verify_password(credentials.password):
        return AuthResult.failure("Invalid password")

    return AuthResult.success(user)  # <- Only success path reaches here

讲解代码： 不佳：“这段代码对用户进行身份验证。” 良好：“我们先检查失败条件（第 4-8 行），并提前返回。只有有效凭据才会进入第 10 行的成功路径。这种‘卫语句’模式可以让正常流程保持不缩进。”

类比

用熟悉的事物解释陌生概念：

概念	类比
API 速率限制	夜店门口的保安，每小时只允许 X 人入场
数据库索引	教科书中的索引，而不是逐页翻阅
缓存	把常用物品放在桌上，而不是放进文件柜
负载均衡	杂货店里的多个收银通道

**规则：**对应关键属性（而非表面相似之处）。说明类比不适用的情况。使用熟悉的领域（而不是其他技术概念）。

处理复杂性

1. 从简单情况开始 - “在基本场景中，会发生 X”
2. 增加一个复杂因素 - “但如果 Y 呢？”展示解决方案如何调整
3. 展示完整情况 - “在生产环境中，你还需要处理 Z”

常见问题

问题	修复方法
大段代码之后才开始解释	将代码与解释交替呈现
“首先，我来解释一下历史……”	从问题开始，而不是从历史开始
假定读者已了解（“如你所知……”）	要么解释清楚，要么链接到前置内容
示例中出现神奇数字/值	使用真实合理且有说明的值
只展示理想流程	展示错误处理
抽象示例（Foo、Bar、Widget）	使用具体领域（User、Order、Payment）

质量检查清单

结构：

• 开篇说明 WHY（动机）
• 复杂度循序渐进（简单 -> 复杂）
• 每个章节都能独立提供价值

代码：

• 所有代码均经过测试且可运行
• 可直接复制粘贴（无隐藏依赖）
• 为关键代码行添加注释

清晰度：

• 不使用未定义的行话
• 为抽象概念提供类比
• 明确列出前置条件

可信度：

• 承认局限性
• 说明何时不该采用此方法

反面模式

模式	修复方法
“只需执行 X”	删除“只需”
“显然……”	仍然解释清楚
仅提供截图的说明	添加文字/代码
大段代码堆砌	拆分成多个部分
“留给读者自行练习”	展示解决方案
“请参阅文档”	总结要点

5. 系统文档（架构指南）

用于编写全面的技术文档，阐明复杂系统的“是什么”与“为什么”。

文档编写流程

1. 探索 - 分析代码库结构、依赖项、设计模式和数据流
2. 构建结构 - 创建逻辑层级，规划渐进式信息呈现，统一术语
3. 撰写 - 先写执行摘要，再从高层架构逐步深入到实现细节

应包含的关键章节

章节	用途
执行摘要	为利益相关者提供一页概览
架构概览	系统边界、组件及交互
设计决策	说明架构选择背后的理由
核心组件	深入介绍每个主要模块/服务
数据模型	架构设计和数据流
集成点	API、事件和外部依赖项
部署架构	基础设施和运维方面的考量
性能特征	瓶颈、优化和基准测试
安全模型	身份验证、授权和数据保护

系统文档最佳实践

• 始终说明设计决策背后的“原因”
• 使用代码库中的具体示例
• 创建有助于读者理解系统的心智模型
• 记录当前状态和演进历史
• 包含故障排查指南和常见问题
• 为不同受众（开发者、架构师、运维人员）提供阅读路径

参考资料

• 句式结构 - 引言、过渡、注意事项和强调短语