1. README#

项目首页，应该包含：

• 项目是什么（一句话）
• 怎么安装（复制粘贴能跑）
• 怎么用（最简单示例）
• 怎么贡献（可选）

不要：

• 长篇大论介绍背景
• 只写给自己看的术语
• 过时信息（README必须是最新的）

2. API文档#

接口定义，应该包含：

• 接口地址
• 请求方法
• 参数说明（类型、必填、示例）
• 返回值（成功/失败示例）
• 错误码

工具推荐：

• Swagger/OpenAPI - 自动生成
• Postman Collection - 可执行
• Markdown表格 - 简单清晰

3. 设计文档#

架构、方案，应该包含：

• 背景（为什么要做）
• 目标（做到什么程度）
• 方案（怎么做的）
• 权衡（为什么选这个方案）
• 风险（可能的问题）

重点：写决策过程，不只是结果。

4. 操作手册#

部署、运维，应该包含：

• 环境要求
• 详细步骤（复制粘贴能执行）
• 常见问题
• 回滚方案

原则：让新手能照着做出来。

原则一：读者是谁#

写之前问自己：

• 给谁看？
• TA知道什么？
• TA想看什么？

给新手的文档：

• 术语要解释
• 步骤要详细
• 例子要简单

给专家的文档：

• 直接给结论
• 细节可以简略
• 重点在决策逻辑

原则二：结构清晰#

用标题层级：

1
# 一级标题 - 文档主题
2
## 二级标题 - 主要章节
3
### 三级标题 - 小节
4
#### 四级标题 - 尽量少用

用列表：

• 无序列表 - 并列事项
• 有序列表 - 有先后顺序

用表格：

• 对比多个选项
• 展示参数

原则三：简洁具体#

不好： “系统会自动处理异常情况。”

好： “当数据库连接失败时，系统会重试3次，每次间隔5秒。如果仍失败，返回错误码500。”

不好： “传入正确的参数即可。”

好： “参数userId必填，类型为字符串，示例：‘user_123’。“

原则四：可执行#

代码示例要真的能跑：

1
# 不好的示例
2
import api
3
api.call()
4

5
# 好的示例
6
import requests
7

8
response = requests.post(
9
    'https://api.example.com/v1/users',
10
    json={'name': '张三', 'age': 25},
11
    headers={'Authorization': 'Bearer your_token'}
12
)
13
print(response.json())

开头要吸引人#

不好： “本文档介绍XX系统的使用方法…”

好： “3分钟上手XX系统，完成你的第一个API调用。”

或者直接给一个能跑的代码。

使用代码块#

大段代码用代码块，不要 inline：

1
// 好
2
public void example() {
3
    System.out.println("Hello");
4
}

不要：public void example() { System.out.println("Hello"); }

标注重要信息#

用引用块：

⚠️ 注意：执行此操作前请备份数据

用加粗： 重要：生产环境需要修改配置文件

及时更新#

文档过时比没有文档更糟。

每次代码变更，问自己：

• README需要更新吗？
• API文档需要更新吗？
• 操作手册需要更新吗？

建议：把文档更新加到Definition of Done。

文档托管#

• GitBook - 美观，适合产品文档
• ReadTheDocs - 适合技术文档
• Notion - 适合团队内部
• GitHub Wiki - 简单，和代码在一起

文档生成#

• Swagger - API文档
• Javadoc/JSDoc - 代码注释生成
• MkDocs - 静态站点生成

写作辅助#

• Grammarly - 语法检查
• Hemingway - 可读性分析
• MarkdownLint - Markdown格式检查

Q: 文档写多长合适？#

A: 能短则短。但必要的细节不能省。

原则：刚好够读者完成任务。

Q: 英文还是中文？#

A: 团队用什么语言就写什么语言。

如果是开源项目，英文为主，关键部分双语。

Q: 怎么让人愿意看？#

A: 没办法，大部分文档确实没人看。

但你要写，因为：

• 出问题时会有人查
• 新入职时必须看
• 你自己三个月后会看

Q: 文档和注释的区别？#

A:

• 注释 - 解释代码为什么这样写
• 文档 - 解释系统怎么用

两者都要有。