mcpp-docs-style git:20260817.f2f9094A

Immutable. This exact content is served forever at /api/v1/blob/6daefa77431674c6.

---
name: mcpp-docs-style
description: Use when writing or editing anything under docs/ (English or 简体中文), README files, or long-form design records — states the register mcpp documentation is written in (declarative, precise, professional), the constructions that are not admitted (question headings, conversational asides, internet slang, figurative jargon), and the bilingual parity rules.
---

# mcpp 文档风格规范

## 适用范围

`docs/**`(含 `docs/zh/**`)、`README.md`、`.agents/docs/**` 的对外部分。

代码注释与 commit message **不受本规范约束** —— 它们的读者、篇幅与目的都不同,
那里允许并鼓励叙述「为什么」以及实测过程。本规范约束的是**面向用户的文档**。

## 一、总原则

文档是**参考资料**,不是博客,也不是聊天记录。判据只有一条:

> 一位不认识作者、只想解决自己问题的工程师,能不能在最短时间内
> 拿到准确的事实,并且不会误以为某个说法比实际更随意或更绝对。

由此得到三条可执行的规则:陈述、精确、克制。

## 二、标题

**标题一律是名词短语或陈述句,不使用疑问句、不使用口语片段。**

疑问句标题把「读者已经知道自己在找什么」这个前提丢掉了 —— 目录里一列问句,
读者要先把每个问句翻译成主题才能定位。

| 不采用 | 采用 |
|---|---|
| 一段话讲完 | 概述 |
| 打什么由谁决定 | 打包内容的决定依据 |
| 哪些 `.cppm` 会被发布 | 发布的接口单元 |
| 消费者的构建会检查什么 | 消费端的构建检查 |
| 怎么消费 | 消费方式 |
| 老版本 mcpp 拿到这种包会怎样 | 旧版本 mcpp 的行为 |
| 为什么两者都不许裁剪 | 两个集合不可裁剪的原因 |
| 这些说法验证到哪一步、在哪台机器上 | 验证范围 |
| The whole idea in one paragraph | Overview |
| What decides what gets packed | What determines the package contents |
| Consuming one | Consuming a package |
| What you may rely on, and what changes | Stability guarantees |

「…的原因」「…的依据」「…的范围」是把 why 型标题转成名词短语的常用形。
**保留 why 本身,去掉疑问语气。**

## 三、词汇

### 不采用的类别

1. **网络用语与口语**:搞定、干活、坑、真香、翻车、打脸、一把梭、白给、
   凉了、炸了、神器、黑科技、敲黑板、划重点。
2. **拟人与比喻性行话**:姊妹篇、腿(fat package 的一份产物)、travel(源码
   「旅行」)、picky、happy path 的中文直译。技术术语本身可以是比喻
   (rpath、sysroot),但**不要新造比喻**。
3. **填充语**:其实、说白了、简单来说、众所周知、显然、当然、值得一提的是。
   如果一件事显然,就不必说;如果不显然,「显然」会让读者怀疑自己。
4. **含糊的程度词**:很快、非常、极其、基本上、差不多。用数字或范围替代 ——
   「2.42×」「64.77s」「四个平台中的三个」。

### 人称

默认**不使用第二人称**。写动作的对象,不写「你」。

- 不采用:你可以在 `mcpp.toml` 里写 …
- 采用:在 `mcpp.toml` 中声明 …

例外:**教程体**文档可以使用第二人称,因为那里读者正在跟着做。教程体是
**列出来的,不是推断的**:`00-getting-started.md`、`01-examples.md`、
`04-build-from-source.md`。其余全部按参考文档处理。

引用 mcpp 自身输出的部分不受此限:`did you mean 'x86_64-linux-musl'?` 与
`your toolchain : …` 是程序打印的原文,**逐字复现是要求,不是文风问题**。
检查脚本因此会先剔除行内代码段再判定。

## 四、句式

- **陈述句优先。** 命令式仅用于操作步骤(「运行 `mcpp build`」)。
- **一句话一个事实。** 从句套从句的长句拆开。
- **不使用反问。**「难道不应该……吗?」没有信息量。
- **不使用感叹号。**
- **破折号克制使用**:插入语用逗号或括号;破折号留给「随后是对前半句的
  重述或收束」这一种用法。

## 五、断言的强度必须与证据相符

这是本规范里最实质的一条,也是最容易违反的一条。

| 证据 | 允许的表述 |
|---|---|
| 跑过、有输出 | 「实测」「测量得到」,并给出数字或报错原文 |
| 读代码推断 | 「按 X 的实现」「由 Y 决定」 |
| 未验证 | 「未验证」「尚无测试覆盖」—— **必须写出来** |

**不要把推断写成实测。** 反例(本仓库真实发生过):把「守卫在原生构建上失效」
写成实测结论,而它是从「`targetTriple` 结构上可能为空」推断的;实际运行时
它非空,结论不成立。判据:**「结构上可能」不等于「运行时确实」——
要么读运行时产物,要么不要写成实测。**

同理,不要用「完全」「永远」「所有平台」这类全称词,除非确实逐个验证过;
写「已在 Linux / macOS / Windows 验证」比写「全平台可用」更有价值,
因为前者可被检验。

## 六、双语对照

`docs/X.md` 与 `docs/zh/X.md` 是**同一份文档的两个版本**,不是两篇文章。

- 章节结构、标题层级、表格行数必须一一对应;
- 代码块、命令、报错原文**逐字相同**,不翻译;
- 术语表统一:module interface unit / 模块接口单元、implementation partition /
  实现分区、import library / 导入库、install name / install name(不译)。
- 改动一侧时**同时改另一侧**。只改一侧会让两份文档随时间分叉,
  而读者无从知道哪一份是新的。

## 七、结构

- 顶部一段引言说明**这份文档回答什么问题**,以及相关文档的链接
  (用「相关文档:」,不用「姊妹篇」)。
- 表格用于枚举与对照,散文用于因果。**不要用散文列举**。
- 「当前边界 / Current limitations」一节是必要的,不是可选的:
  没有写出边界的文档,读者只能靠踩到才知道。

## 八、机器检查

规则里可判定的那一半由 `.github/tools/check_docs_style.sh` 执行:

```
bash .github/tools/check_docs_style.sh
```

它检查三条:标题不是疑问句/口语片段;参考文档不使用第二人称;
`docs/X.md` 与 `docs/zh/X.md` 的标题结构一致(按层级序列比对,
并剔除代码块内的 `#` 注释 —— 第一版脚本把 ```sh 块里的 `# GET, never HEAD`
数成了标题,报出一个并不存在的结构分歧)。

**它不检查第五节** —— 断言强度与证据是否相符需要读者判断,而那是本规范里
最重要的一条。脚本能做的事不等于规范的全部。

## 九、自检清单

提交文档改动前:

```
[ ] 标题没有疑问句、没有口语片段
[ ] 没有网络用语、没有新造比喻
[ ] 没有第二人称(教程体除外)
[ ] 每条「实测」都有数字、路径或报错原文
[ ] 没有未经验证的全称断言
[ ] 中英两版结构对应,代码块逐字一致
[ ] 有「当前边界」一节
[ ] `bash .github/tools/check_docs_style.sh` 通过
```