Repository navigation
10 documentation standards
omeyang edited this page Sep 16, 2026
·
1 revision
本文档定义技术文档的书写规范，确保文档职责唯一、简约准确、专业可读。
| 目标 | 说明 |
|---|---|
| 统一编号 | 文件名以编号开头（如 01-xxx.md） |
| 命名准确 | 文件名简短、准确、见名知义，使用 kebab-case |
| 职责唯一 | 每个文档只负责一个职责 |
| 实质内容 | 干净利落，无冗余内容 |
| 时效准确 | 只记录最新状态 |
| 关联准确 | 所有引用和链接必须有效 |
| 简约精炼 | 代码块不超过 5 行，图表优先 |
| 控制篇幅 | 单个文档不超过 800 行 |
| 专业表述 | 使用专业技术语言，杜绝口语化 |
| 真实可靠 | 基于实际代码和数据，不猜测臆想 |
每个文档必须想清楚自己的职责，只负责一个职责。
检查方法：
- 文档标题能否用一句话概括？
- 所有章节是否围绕同一职责展开？
- 是否存在"顺便讲了 XX"的情况？
代码块不超过 5 行，超过则用 Mermaid 图表替代。
- 数据结构 ->
classDiagram - 算法流程 ->
flowchart - 系统交互 ->
sequenceDiagram - 状态机 ->
stateDiagram - 架构图 ->
graph或 C4
不同环境使用同一套代码，通过配置切换。文档仅标注差异点，不做全量对比。
必须使用行业标准术语，必须删除口语化表达和自问自答。
| 口语化表达 | 专业术语 |
|---|---|
| "可能会出现问题" | "在高并发场景下存在竞态条件" |
| "大概需要 100ms" | "P95 延迟为 95ms，P99 延迟为 120ms" |
| "应该不会有问题" | "经过压力测试验证，系统在 QPS 8000 时稳定运行" |
所有设计决策基于实际数据，标注数据来源、采集时间、查询方法。
必须基于实际代码和数据，禁止猜测、臆想、假设。
禁用词汇：
- "可能"、"大概"、"应该"、"估计"、"也许"、"或许"
每一行都有实质内容，不能为了写文档而写文档。
禁止的形式主义内容：
- 联系方式、维护人、更新频率
- 总文档数、总阅读时间
- 文档依赖关系图、文档成熟度矩阵
- 待办事项列表、变更日志
- FAQ、Q&A、常见问题
删除测试法：如果删除这段内容，技术方案仍然完整，则该内容应删除。
文档只描述"现在是什么样"，不写"曾经是什么样"。历史信息单独组织在 ADR 目录。
所有文档引用、代码位置引用、数据来源引用必须有效。
| 引用类型 | 格式 |
|---|---|
| 文档引用 | [描述](相对路径) |
| 代码位置 | `文件路径:行号` |
| 数据来源 | [来源描述](附录位置) |
使用编号建立逻辑关系，目录下必须有 README.md 索引。
| 编号类型 | 格式 | 示例 |
|---|---|---|
| 主文档 |
01-, 02-
|
01-overview.md |
| 附录文档 |
01A-, 01B-
|
04A-detailed-examples.md |
| ADR |
001-, 002-
|
adr/001-choose-cache.md |
剖析代码的文档必须标注代码仓库、分支、提交信息。
格式：
**代码基准**：`仓库名` @ `分支名` (`提交hash`, 日期)发现某个方向不可行时，必须立即记录决策，包含拒绝理由和验证方法。
| 场景 | 规则 | 示例 |
|---|---|---|
| 中文与英文 | 必须加空格 | 使用 MongoDB 数据库 |
| 中文与数字 | 必须加空格 | 共 100 个文件 |
| 中文与代码 | 必须加空格 | 使用 NewCache() 函数 |
- 中文内容用中文标点（句号
。、逗号，、顿号、） - 并列词语用顿号：
MySQL、PostgreSQL 以及 MongoDB - 时间起止用一字线：
2024 年 1 月—6 月 - 数值范围用浪纹线：
8000～12000 QPS - 复合名词用短横线：
go-service
- 统计数据必须用阿拉伯数字
- 大数字应该用"万/亿"简化：
1250 万条记录 - 禁止使用概数（如"三五天"、"七八十个"）
必须保持官方大小写：MongoDB、MySQL、Go（不是 Golang）、Kubernetes、gRPC。
列表项末尾标点必须保持一致：要么都加句号，要么都不加。
- 绝对要求用"必须"（MUST）
- 绝对禁止用"禁止"（MUST NOT）
- 强烈建议用"应该"（SHOULD）
- 可选建议用"可以"（MAY）
- 避免模糊表述（"建议"、"推荐"、"最好"、"尽量"）
不超过 4 级（H1-H4）。如果需要更深层级，说明文档需要拆分。
- 使用名词短语（如"缓存策略"）
- 避免动词开头（不要"如何实现缓存"）
- 简洁准确（不超过 15 字符）
- 单个文档不超过 800 行
- 超过时拆分为"主文档 + 附录"
- 列数应该不超过 5 列
- 超过时拆分为多个表格或改用列表
- 文件名以编号开头，使用 kebab-case
- 文档标题能用一句话概括
- 文档总行数不超过 800 行
- 章节层级不超过 4 级
- 代码块不超过 5 行
- 删除口语化表达和自问自答
- 所有数据有来源
- 删除形式主义和表演性内容
- 只记录最新状态
- 所有引用和链接有效
- 中英文、中文数字之间加空格
- 并列词语用顿号，连词前不用顿号
- 连接号根据用途选择：一字线/短横线/浪纹线
- 强制性词汇使用加粗
本页由 Maat 仓库的 scripts/sync-wiki.sh 自动生成，请勿直接编辑。