文档规范
文档类型
技术文档
- 架构设计文档
- API 接口文档
- 数据库设计文档
- 部署运维文档
项目文档
- 需求文档
- 设计文档
- 测试文档
- 变更日志
文档格式
格式要求
- 使用 Markdown 格式编写
- 文件编码使用 UTF-8
- 文件名使用小写字母，下划线分隔
文档结构
# 文档标题
## 概述
简要描述文档内容和目的。
## 目录
列出文档的主要章节。
## 正文
详细内容...
## 附录
补充说明、参考资料等。文档内容规范
语言规范
- 使用中文编写
- 语言简洁明了
- 避免歧义
- 专业术语统一
代码示例
- 使用正确的代码块语法
- 添加语言标识
- 代码格式规范
- 添加必要的注释
图表规范
- 图表清晰易读
- 添加标题和说明
- 使用统一的风格
API 文档
文档工具
- 使用 Swagger/OpenAPI
- 自动生成文档
- 保持文档与代码同步
文档内容
- 接口描述
- 请求参数
- 响应格式
- 错误码说明
文档管理
版本控制
- 文档纳入版本控制
- 定期更新
- 记录变更历史
文档审核
- 文档需要审核发布
- 定期归档旧版本
- 文档权限管理
最佳实践
- 文档及时更新
- 保持文档与代码一致
- 使用模板统一格式
- 定期清理过期文档