技术文档

为不同的受众和目的编写清晰、可维护的技术文档。

文档类型

README

• 这是什么以及为什么存在
• 快速入门（5 分钟内首次成功）
• 配置和使用
• 贡献指南

API 文档

• 端点参考，含请求/响应示例
• 认证和错误码
• 速率限制和分页
• SDK 示例

操作手册

• 何时使用此操作手册
• 前置条件和所需访问权限
• 分步操作流程
• 回滚步骤
• 升级路径

架构文档

• 上下文和目标
• 高层设计及图表
• 关键决策和权衡
• 数据流和集成点

入职指南

• 环境搭建
• 关键系统及其连接方式
• 常见任务操作演练
• 什么问题该找谁

原则

1. 为读者而写——谁在读这个，他们需要什么？
2. 从最有用的信息开始——不要把重点埋在最后
3. 展示而非描述——代码示例、命令、截图
4. 保持内容最新——过时的文档比没有文档更糟糕
5. 链接而非复制——引用其他文档而不是复制内容