Documents 文档编写规则¶

结论：每篇文档先写清读者和用途，再使用最小头信息。先写结论，后写依据。先保证清晰，再追求完整。

0. 文档控制¶

本规则与上位规则冲突时，执行上位规则。

1. 目的¶

本规则统一 Documents 中文档的写法。

本规则解决以下问题：

1. 新文档应放在哪里。
2. 文档开头应写哪些信息。
3. 不同用途的文档应如何组织结构。
4. 标题、句子、表格、图表和链接应如何使用。
5. 文档何时升级版本、何时归档。
6. 怎样判断一篇文档已经写完。

2. 适用范围¶

本规则适用于 projects、areas、resources 和 inbox 中的 Markdown 文档。

本规则适用于新建文档，也适用于发生实质修改的旧文档。

下列文件不强制使用完整头信息：

• MANIFEST.md：Documents 根的权威清单。
• INDEX.md：目录文件。
• README.md：项目或目录入口。
• templates/ 中的模板文件。
• 自动生成或第三方导入的文件。
• 20-项目资料 中的过渡文件。

旧文档发生实质修改时，补加头信息。不要为了补头信息批量改写全部旧文档。

3. 文件分类¶

3.1 先判断文档用途¶

flowchart TD
  A["读者要用文档做什么"] -->|学习新技能| T["教程"]
  A -->|完成已知任务| H["操作指南或 SOP"]
  A -->|查询事实、字段或命令| R["参考"]
  A -->|理解原因、背景和取舍| E["说明或调研"]
  A -->|固定一项长期决策| D["决策记录"]
  A -->|保存短时信息| N["笔记"]

3.2 文档类型¶

每篇文档只选择一种主类型。内容跨越两种类型时，拆成两篇文档并用相对链接连接。

4. 头信息¶

4.1 格式¶

头信息必须位于文件第一行，并使用 YAML。

---
slug: /areas/example-document
title: 示例文档
type: how-to
status: draft
version: "0.1"
updated: "2026-10-28"
keywords:
  - 示例
  - 文档规范
  - 操作指南
description: 用一句话说明文档解决的问题和读者可以获得的结论。
---

4.2 必需字段¶

4.3 条件字段¶

Docusaurus 使用 slug、title、keywords 和 description 生成页面元数据。当前目录暂不发布网站，也应按同一模型填写。以后迁移到静态站点时，不需要重建文档标识。

4.4 字段约束¶

• slug 示例：/areas/standards/document-writing-rules。
• slug 不超过 120 个字符。
• title 控制在 2 到 60 个字符。
• title 不加句号。
• description 只写一句。
• description 控制在 20 到 120 个字符。
• keywords 使用概念词，不使用无意义标签。
• updated 只在内容发生实质变化时更新。
• 不添加无使用者的字段。

5. 文件命名¶

5.1 一般规则¶

文件名必须清楚、稳定、可搜索。

• 使用中文短名或小写 ASCII kebab-case。
• 不使用空格。
• 不使用 final、new、latest、最终版 等易失效词。
• 不使用日期作为普通文档的主文件名。
• 同一目录内不保留标题相同、内容不同的文件。

可能发布到网站的文档优先使用小写 ASCII 文件名，例如 document-writing-rules.md。

个人内部文档可以使用中文名，例如 文档编写规则.md。

5.2 日期与版本¶

需要固定版本的交付物使用以下格式：

YYYY-MM-DD-topic-vNN.ext

示例：

2026-10-28-document-writing-rules-v01.md

文件生成后，不通过改名表达版本变化。版本记录写进正文或 version 字段。

6. 正文结构¶

6.1 通用顺序¶

除索引、README 和模板外，正文按以下顺序组织：

1. 一级标题。
2. 一句话结论。
3. 目的或问题背景。
4. 主要正文。
5. 风险、限制或例外。
6. 下一步或完成标准。
7. 来源与证据。

结论写在标题后的第一段。读者不读全文时，也能知道文档要回答什么。

6.2 标题层级¶

• 一级标题只出现一次。
• 二级标题表示主要章节。
• 三级标题表示章节内的小节。
• 不跳级使用标题。
• 标题使用名词短语或动作短语。
• 标题末尾不加句号或冒号。
• 同级标题表达同一层级的对象。

6.3 段落¶

• 每段只写一个主题。
• 每段优先控制在 3 到 5 句。
• 先用一句话写结论。
• 再写依据、条件或动作。
• 不用长段落隐藏关键结论。

7. 写作规则¶

7.1 读者与目标¶

动笔前写清四项：

1. 读者是谁。
2. 读者要完成什么。
3. 读者读完后要做什么决定。
4. 文档不覆盖什么。

至少再问一次：“读者需要这条信息才能行动吗？”答案是否定时，删除信息或移到其他文档。

7.2 句子¶

• 每句只写一个动作或一个事实。
• 每句最多包含一个逻辑关系。
• 使用主动语态。
• 使用具体动词。
• 一个概念只用一个术语。
• 术语第一次出现时解释一次。
• 代词必须有明确对象。
• 不写双重否定。
• 不叠加情态词。
• 条件放在动作前。

步骤句不超过 25 个汉字。说明句不超过 35 个汉字。

7.3 用词¶

• 使用常用词。
• 使用具体对象和数值。
• 删除空泛修饰词。
• 删除宣传词和网络流行词。
• 不写“进行 + 名词”的空结构。
• 需要否定时写“不”或“禁止”。
• 不确定时写清不确定的范围和原因。

7.4 事实与判断¶

文档必须区分三类信息：

数字必须带单位、时间范围和来源。无法核验的数字不写成事实。

引用外部材料时保留原始标题和链接。链接失效风险高的材料增加访问日期。

8. 排版规则¶

8.1 列表¶

• 步骤使用编号列表。
• 并列项目使用无序列表。
• 每个编号只对应一个动作。
• 每个列表项保持相同语法结构。
• 列表项超过 7 个时，检查是否需要分组。

8.2 表格¶

表格用于比较、字段说明和矩阵。

• 每个单元格只放一个信息。
• 表头必须说明维度。
• 不使用无表头的表格。
• 不把长段落塞进单元格。
• 表格后补充结论或限制。

8.3 代码与命令¶

• 代码块必须标注语言。
• 命令与输出分开。
• 命令示例使用可复制格式。
• 不把秘密、令牌和个人数据写入示例。
• 破坏性命令前写警告和后果。

8.4 强调¶

• 粗体只用于关键结论、警告和操作对象。
• 不大段加粗。
• 不使用全大写表达强调。
• 不用颜色作为唯一信息载体。

9. 图表与图片¶

流程、层级、状态、比较和组件关系优先使用图表。

• 流程图使用 Mermaid。
• 每张图只保留一个主要焦点。
• 每张图默认不超过 9 个节点。
• 节点只表达一个概念。
• 连线只表达一个关系。
• 图中文字与正文术语一致。
• 图表前写一句说明。
• 图表后只补充图表之外的结论、风险或动作。
• 图片必须有替代文本。
• 图片说明写来源和日期。

图表不能代替警告、代码、命令和错误信息。

10. 链接与引用¶

10.1 链接¶

• 内部文档使用相对路径。
• 外部材料使用完整 URL。
• 链接文字说明目标内容。
• 不使用“点击这里”“更多”等空链接文字。
• 同一目标只保留一个权威链接。
• 链接前检查目标是否存在。

10.2 来源¶

研究、标准、SOP 和正式报告必须列出主要来源。

来源至少包含：

1. 作者或组织。
2. 文档标题。
3. 链接或本地路径。
4. 发布日期或访问日期。

来源只列真正支撑结论的材料。不要用大量链接代替分析。

11. 状态与版本¶

11.1 状态¶

11.2 版本¶

标准、SOP、决策记录和正式报告使用两段版本号：主版本.次版本。

• 首次发布使用 1.0。
• 修正文字、链接和示例时增加次版本。
• 改变规则、步骤、结论或适用范围时增加主版本。
• 状态从 draft 进入 review 时更新 updated。
• 状态从 review 进入 active 时填写生效日期。

被替代的文档保留原文。旧文档增加 status: superseded，并链接新文档。

12. AI 辅助写作¶

AI 可以用于提纲、草稿、摘要、格式转换和链接初检。

AI 不承担以下责任：

• 事实核验。
• 数据计算。
• 隐私判断。
• 合规判断。
• 最终批准。

AI 辅助生成的数字、引用、命令和结论必须人工核验。

AI 不得被写成作者。作者对发布内容负责。

13. 安全与隐私¶

• 不把密码、令牌、私钥和恢复码写入文档。
• 个人数据只保留完成任务所需的最少内容。
• 敏感材料遵循所在目录和项目规则。
• 截图前检查用户名、路径、令牌和通知内容。
• 对外分享前检查元数据、隐藏内容和附件。

数据丢失、权限、安全和不可逆操作必须写警告。警告放在操作步骤之前。

14. 旧文档迁移¶

旧文档不批量改写。按以下顺序迁移：

1. 修改一篇旧文档时，先补必需头信息。
2. 检查标题和结论是否清楚。
3. 检查步骤、表格、链接和图表。
4. 更新 status 和 updated。
5. 保留原文件路径，除非归档规则要求迁移。
6. 迁移完成后校验链接和摘要。

五篇以上的批量迁移先生成清单。删除、覆盖或批量改名先取得明确确认。

15. 完成检查¶

发布或归档前逐项检查：

• 文件位于正确目录。
• 文件名清楚且稳定。
• 头信息字段齐全。
• YAML 语法有效。
• title 与一级标题一致。
• slug 唯一且稳定。
• description 是一句完整说明。
• keywords 为 3 到 8 个。
• 第一段写明结论。
• 每段只有一个主题。
• 标题层级连续。
• 术语前后一致。
• 数字和事实有来源。
• 内部链接可打开。
• 外部链接可打开。
• 代码块标注语言。
• 图片有替代文本。
• 风险与限制已写明。
• 状态和版本正确。
• 无密码、令牌和个人敏感数据。

文档未通过检查时保持 draft 或 review。

16. 最小模板¶

---
slug: /areas/example-document
title: 示例文档
type: how-to
status: draft
updated: "2026-10-28"
keywords:
  - 示例
  - 指南
  - 文档规范
description: 用一句话说明文档解决的问题和读者可以获得的结论。
---

# 示例文档

> 结论：写出一句话结论。

## 1. 目的与范围

写明读者、问题和边界。

## 2. 正文

按任务顺序写清步骤、依据和结果。

## 3. 风险与限制

写明适用条件和失败后果。

## 4. 下一步

写明读者接下来要做什么。

## 5. 来源

列出主要来源。

17. 调研依据¶

本规则参考以下公开资料：

1. Docusaurus Docs：Markdown Front Matter：slug、title、keywords、description 等字段的定义。
2. Diátaxis：教程、操作指南、参考和说明四类文档。
3. GitHub Docs：Best practices：读者、目的、可读性、可扫描性和内容类型。
4. Google developer documentation style guide：清晰、一致和面向读者的写作原则。
5. Microsoft Writing Style Guide：简洁、直接、先写重点。
6. Write the Docs：可扫描、一致、及时和可发现的文档。
7. CommonMark：Markdown 兼容语法。
8. 文件与目录管理规则：目录、项目 ID、迁移和归档约束。

18. 版本记录¶