技术文档撰写

何时使用此技能

• 撰写技术规格说明
• 创建架构文档
• 记录系统设计
• 编写运行手册和操作指南
• 创建设开发者文档
• API 文档
• 用户手册和指南
• 发布说明和更新日志

指示

步骤 1：了解您的受众

开发者受众：

• 专注于实现细节
• 包含代码示例
• 可以使用技术术语
• 展示如何做，而不仅仅是做什么

运维/运营受众：

• 专注于部署和维护
• 包含配置示例
• 强调监控和故障排除
• 提供运行手册

经理/利益相关者受众：

• 高层次概述
• 业务影响
• 尽量减少技术术语
• 关注成果

最终用户受众：

• 简单清晰的语言
• 分步说明
• 视觉辅助（截图、视频）
• 常见问题解答部分

步骤 2：选择合适的文档类型

技术规格说明：

# [功能名称] 技术规格说明

## 概述
简要描述此规格说明涵盖的内容

## 问题陈述
我们要解决什么问题？

## 目标和排除项
### 目标
- 目标 1
- 目标 2

### 排除项
- 我们明确不做的内容

## 解决方案设计
### 高层架构
### 数据模型
### API 契约
### 用户界面

## 实施计划
### 阶段 1
### 阶段 2

## 测试策略

## 安全考量

## 性能考量

## 监控与告警

## 发布计划

## 回滚计划

## 未决问题

## 参考资料

架构文档：

# 系统架构

## 概述
高层系统描述

## 架构图
[插入图表]

## 组件
### 组件 1
- 职责
- 技术栈
- 接口

### 组件 2
...

## 数据流
数据如何在系统中流动

## 关键设计决策
### 决策 1
- 背景
- 考虑的选项
- 做出的决策
- 理由

## 技术栈
- 前端：React， TypeScript
- 后端：Python， FastAPI
- 数据库：PostgreSQL
- 基础设施：AWS， Docker， Kubernetes

## 可扩展性
系统如何扩展

## 安全性
认证、授权、数据保护

## 监控与可观测性
指标、日志、追踪

## 灾难恢复
备份和恢复程序

## 未来考量

运行手册：

# [服务名称] 运行手册

## 服务概述
此服务的功能

## 依赖项
- 服务 A
- 服务 B
- 数据库 X

## 部署
### 如何部署
```bash
./deploy.sh production

回滚

./rollback.sh

监控

关键指标

• 请求率
• 错误率
• 延迟

仪表板

• 生产仪表板
• 告警

常见问题

问题 1：高延迟

症状：响应时间 > 1秒
诊断：检查数据库连接池
解决方法：重启服务或扩容

问题 2：内存泄漏

症状：内存使用量随时间增长
诊断：检查堆转储
解决方法：重启服务，在预发布环境调查

故障排除

如何查看日志

kubectl logs -f deployment/service-name

如何访问指标

curl https://api/metrics

紧急联系人

• 值班：PagerDuty
• 团队 Slack：#团队名称

**API 文档**：
```markdown
# API 文档

## 认证
所有请求都需要认证：
```bash
curl -H "Authorization: Bearer 您的令牌" \
  https://api.example.com/endpoint

端点

获取用户列表

GET /api/v1/users

参数：

示例请求：

curl -X GET "https://api.example.com/api/v1/users?page=1&limit=20" \
  -H "Authorization: Bearer 您的令牌"

示例响应：

{
  "data": [
    {
      "id": 1,
      "name": "张三",
      "email": "zhangsan@example.com"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

错误响应：

### 步骤 3：撰写指南

**清晰度**：
- 使用简单直接的语言
- 每句表达一个想法
- 段落简短（3-5 句）
- 定义技术术语
- 尽可能避免使用术语

**结构**：
- 使用层级标题（H1， H2, H3）
- 将内容分成多个部分
- 对于多项内容使用列表
- 对于结构化数据使用表格
- 为长文档添加目录

**示例**：
- 包含代码示例
- 提供图表
- 展示前后对比
- 真实场景

**完整性**：
- 涵盖前提条件
- 包含错误处理
- 记录边缘情况
- 解释为什么，而不仅仅是怎么样
- 链接到相关文档

**一致性**：
- 术语一致
- 格式一致
- 代码风格一致
- 结构一致

### 步骤 4：视觉辅助

**架构图** (Mermaid)：
```mermaid
graph TB
    A[客户端] -->|HTTP| B[负载均衡器]
    B --> C[Web 服务器 1]
    B --> D[Web 服务器 2]
    C --> E[数据库]
    D --> E

时序图：

sequenceDiagram
    客户端->>+服务器: 请求
    服务器->>+数据库: 查询
    数据库-->>-服务器: 数据
    服务器-->>-客户端: 响应

流程图：

flowchart TD
    A[开始] --> B{是否有效？}
    B -->|是| C[处理]
    B -->|否| D[错误]
    C --> E[结束]
    D --> E

代码块 带语法高亮：

def calculate_total(items: List[Item]) -> Decimal:
    """计算商品总价。"""
    return sum(item.price for item in items)

截图：

• 用于界面文档
• 标注重要部分
• 随界面变更保持更新

表格：

步骤 5：审阅与完善

自我审阅清单：

• 开头阐明清晰目的
• 信息逻辑流畅
• 所有术语均已定义
• 代码示例经过测试
• 链接有效
• 图表清晰
• 无拼写或语法错误
• 格式一致
• 有目录（如需要）
• 包含最后更新日期

获取反馈：

• 请目标受众中的某人审阅
• 测试说明（他们能照着做吗？）
• 检查是否有信息遗漏
• 验证准确性

维护文档：

• 随代码变更而更新
• 对文档进行版本控制
• 归档过时文档
• 定期审阅

文档模板

技术规格说明模板

# [功能名称] 技术规格说明

**作者**：[您的姓名]
**日期**：[日期]
**状态**：[草稿/审阅中/已批准]

## 概述
[1-2 段描述本文档涵盖的内容]

## 背景
[背景和动机]

## 目标
- 目标 1
- 目标 2

## 排除项
- 我们不做的内容

## 详细设计
[技术细节]

## 考虑过的替代方案
[其他方法及未选择的原因]

## 时间线
- 第 1 周：...
- 第 2 周：...

## 未决问题
- 问题 1
- 问题 2

## 功能特性
- 特性 1
- 特性 2

## 安装

### 前提条件
- Node.js >= 14
- npm >= 6

### 设置
```bash
git clone https://github.com/user/project.git
cd project
npm install

使用方法

npm start

配置

环境变量：

• API_KEY：您的 API 密钥
• PORT：服务器端口 (默认: 3000)

开发

npm run dev
npm test

部署

[部署说明]

贡献指南

[贡献指南]

许可证

MIT

### 更新日志模板
```markdown
# 更新日志

## [1.2.0] - 2024-01-15

### 新增
- 新功能 X
- 支持 Y

### 变更
- 提升了 Z 的性能
- 将依赖 A 更新至 v2.0

### 修复
- 修复了用户无法登录的错误
- 修复了后台任务中的内存泄漏

### 弃用
- 旧的 API 端点 /v1/users（请使用 /v2/users）

### 移除
- 移除了旧的认证方法

### 安全
- 修复了评论中的 XSS 漏洞

## [1.1.0] - 2024-01-01
...

撰写技巧

使用主动语态

✅ 好： "系统发送通知"
❌ 差： "通知被系统发送"

简洁明了

✅ 好： "点击保存以保存更改"
❌ 差： "为了保存您的更改，您应该点击保存按钮"

使用示例

✅ 好：
"设置超时时间（秒）：
```yaml
timeout: 30

❌ 差：
“请适当配置超时参数”

### 分解复杂性

✅ 好：
“部署步骤：

1. 构建镜像
2. 推送到仓库
3. 更新部署
4. 验证上线”

❌ 差：
“通过构建并推送镜像到仓库，然后更新部署并验证上线成功来完成部署”

## 需避免的常见错误

1. **预设知识**：定义术语，解释背景
2. **文档过时**：与代码保持同步
3. **缺少示例**：始终包含示例
4. **无视觉辅助**：对复杂概念使用图表
5. **结构混乱**：使用标题和章节
6. **被动语态**：使用主动语态
7. **术语过多**：为受众写作
8. **无版本信息**：标注文档日期和版本
9. **遗漏错误情况**：记录可能出错的地方
10. **不维护**：定期更新

## 最佳实践

1. **为受众写作**：符合他们的知识水平
2. **从为什么开始**：解释目的
3. **展示，而不仅仅是说明**：使用示例
4. **保持一致**：术语、风格、结构
5. **测试您的文档**：别人能照着做吗？
6. **对文档进行版本控制**：与代码版本同步
7. **使用模板**：保持文档间一致性
8. **链接相关文档**：帮助读者找到更多信息
9. **随代码更新**：文档是代码的一部分
10. **定期审阅**：每季度进行文档审阅

## 工具

**图表工具**：
- Mermaid (基于 Markdown)
- Draw.io
- Lucidchart
- PlantUML

**文档平台**：
- GitBook
- Docusaurus
- MkDocs
- Sphinx

**风格检查器**：
- Grammarly
- 赫敏·阿不思·平心而论编辑器 (Hemingway Editor)
- Vale

**截图工具**：
- Snagit
- CloudApp
- Loom (用于视频)

## 示例

### 示例 1：基本用法
<!-- 在此处添加示例内容 -->

### 示例 2：高级用法
<!-- 在此处添高级示例内容 -->