简明技术中文
目标：读者读一遍就不会读错。做法：限制用词，限制句式，一句一事。
完整规则见 规范.md，词表见 词表.md。本文件只列最常用的部分。
模式
- 常规模式（默认）：执行全部【必须】规则和词表的自动检查条目。【建议】规则只在明显时处理。
- 严格模式：用户说「严格」「全部规则」时，执行全部规则。
用户没有说明时用常规模式。
写之前先分类
- 操作句：告诉读者做什么。放在编号列表里，动词开头，不超过 30 字。
- 描述句：其他句子。不超过 40 字。
字数算法：每个汉字计 1，每个英文单词或数字串计 1，行内代码计 1，标点不计。
必须遵守的规则
词：
- 一个概念全文只用一个词。不换同义词。（1.1）
- 不用「进行」「加以」「作出」「予以」加动词。直接用动词。（1.4）
- 不用没有数值的程度词：「很」「非常」「较」「大量」「尽快」「及时」。写数值或条件。（1.5）
- 缩写首次出现写全称并括注，之后固定写法。（1.6）
- 不用黑话：「赋能」「抓手」「闭环」「拉通」「沉淀」「痛点」「对标」「打法」「拉齐」。（1.7）
句：
- 一句只说一件事。分号不能用来把两句并成一句。（2.2）
- 操作句用祈使句，不写「请」「您」「用户需要」「应该」。（2.3）
- 用主动句，写出执行者。「被」「由」「受到」是信号。（2.4）
- 条件写在动作前面：「如果 X，做 Y」。不放句尾，不放括号。（2.5）
- 一句最多一个否定。不用「不得不」「不无」「没有……不」。（2.6）
- 名词前的修饰语不超过 15 字。连续的「的」是信号。（2.7）
- 「其」「该」「此」「它」只指代上一句的对象。否则重复名词。不用「相关」「上述」。（2.8）
- 不用反问、设问、感叹。（2.9）
段和步骤：
- 一段一个主题，不超过 6 句。（3.1、3.2）
- 步骤用编号列表，每个编号一个动作。不在正文里写「首先……然后……」。（3.3、4.1）
- 不用「等」结尾的开放列举。列全，或写数量加「包括」。（3.5）
- 警告独立成段，放在它针对的步骤之前，以「警告：」开头。（4.3）
- 人的动作用祈使句；系统的行为写「系统 + 动词」。（4.4）
- 前置条件单独列出，放在步骤之前。（4.5）
数字：
- 阿拉伯数字，数字与单位之间空格。（5.1）
- 不用数字后的「以上」「以下」「以内」。用「大于」「不小于」「不超过」，或「3 至 5（含）」。（5.2）
- 不用相对时间：「明天」「近期」「稍后」「尽快」。用绝对日期或时长。（5.3）
- 操作句里不用「约」「几」「若干」「多次」。写数值。（5.4）
- 减少不用「倍」。百分比和百分点分开。（5.5）
标记：
- 界面元素名用「」括起，和界面文字一致。（6.1）
- 代码、命令、路径、字段名用代码标记，原样保留。（6.2）
词表速查
最常撞上的 20 条。完整表见 词表.md。
| 不用 | 用 |
|---|---|
| 「进行安装」 | 安装 |
| 「相关配置」 | 写出具体对象 |
| 「支持 A、B 等」 | 列全，或「包括 3 种：A、B、C」 |
| 「10 以上」 | 大于 10 / 不小于 10 |
| 「大概 5 秒左右」 | 5 秒 |
| 「尽快」 | 30 分钟内 |
| 「如果失败的话」 | 如果失败 |
| 「检查一下」 | 检查 |
| 「出现错误的情况」 | 出现错误时 |
| 「应该」「务必」「一定要」 | 必须（强制）/ 建议（推荐） |
| 「不得」「不准」 | 禁止 |
| 「单击」「点按」 | 点击 |
| 「删掉」「去掉」 | 删除 |
| 「开启功能」 | 启用功能 |
| 「打开程序」 | 启动程序 |
| 「登出」 | 退出登录 |
| 「键入」 | 输入 |
| 「入参」「出参」 | 参数 / 返回值 |
| 「登陆」「帐号」「缺省」 | 登录、账号、默认 |
| 「报错」（名词） | 错误 |
一词一义里最常错的 4 个：
- 打开：只用于文件、窗口、页面、连接。功能用「启用」，程序用「启动」。
- 可以：只表示允许。能力用「支持」。
- 问题：只表示疑问。故障、错误、缺陷分开写。
- 更新：只用于数据和内容。版本用「升级」。
工作流程
-
判断内容类型。营销、叙事、法律原文不用本规范。
-
判断模式。默认常规模式。
-
写或改写。先定术语，再写句子。操作内容用编号列表。
-
如果结果保存成了文件，运行检查脚本：
bashpython3 tools/check.py 文件.md聊天回答这类没有编号步骤的内容，加
--kind 描述。 -
修复全部【必须】级别的发现。【建议】级别的按判断处理。
-
改写别人的文稿时，不改变事实、数字、条件和确定程度。原文说「可能」，改写后仍是「可能」。
不要做的事
- 不改写代码、命令、路径、字段名、URL。
- 不为了缩短句子而删除条件、例外和警告。
- 不把「可能」改成「会」，不把「建议」改成「必须」。
- 不给原文没有的数字、日期和时限编一个。缺信息时写「待确认」。
- 不把规范用在它不适用的文体上。
检查脚本的局限
脚本只查句法。它查不出事实错误、术语选错、逻辑顺序错。它用「编号列表项」判断操作句，用「的」的数量近似长定语，用几个标记词近似被动句。所有发现都要人工确认。
