docs: 新增说人话与图示优先两条规则,登记跨仓库笔记

This commit is contained in:
cat-shark
2026-11-20 09:36:54 +08:00
parent 84ce312e4b
commit 281585698b
7 changed files with 241 additions and 4 deletions
+38
View File
@@ -0,0 +1,38 @@
# 说人话
- **功能**:约束回复、解释与交付说明的用词层级,禁止拿行话统称代替具体内容,让没读过实现的人也能对上号。
- **何时用**:写面向用户的回复、解释方案与取舍、写交付说明、做设计或规则评审时(**强制**);用户说「什么意思」「太复杂」「说人话」时。
## 规则
### 先给具体,再给统称
- 回答「是什么 / 缺什么 / 怎么改」,第一句就写具体对象和具体取值:什么颜色、多宽、偏移多少、几毫秒、落在哪个文件哪一处。
- 统称只在具体项列完之后出现,用来收口,不用来开场。禁止先抛一个统称(「三类 X 机制」「Y 体系」)再让读者猜它包含什么。
### 日常概念不用行话包装
- 颜色、字号、间距、圆角、层叠顺序这类东西就叫「取值」或「常量」,不叫 token、design token、设计令牌。
- 外部框架的造词(token、primitive、style lock、lint 规则名等)要进中文回复,先翻成动作描述:「先查有没有现成的、没有再画」「按钮的悬停、按下、聚焦三种样子都要有」。
- 必须保留的外部专名(Flyway、Sa-Token 这类产品或命令)按原样写,但首次出现要附一句中文说明它干什么。
### 一句话最多一层抽象
- 不写「X 体系的 Y 机制」「三类 Z」这种只描述结构、不落到对象的句子;一律改成「哪三个东西、各是什么、分别用在哪」。
- 被问「这是什么意思」时,先用人话答完,再决定要不要补术语名;不要反过来先讲名字再解释。
### 不借术语省字
- 术语为了指向准确,不为缩短句子;省下来的字由读者承担。
- 同一个抽象统称在一段里出现两次以上,说明自己在绕,停下来把第一句改写成具体项。
### 自查
- 把回复里每个统称问一句「它具体指哪几个东西」;答不出、或要绕一圈才答得出,就重写成具体项。
- 提前写出「用户最可能追问的那一句」;用户已经追问过,就说明前一条没做到,下次直接写进去。
- 用户明确说过「说人话」之后,后续同类内容直接按本条执行,不逐次解释为什么之前换了个说法。
## 不在约束内
- 代码标识符、字段名、命令、路径按代码原样书写,不为「说人话」改造它们。
- 业务概念名仍以 `lpt-docs/docs/concepts/README.md` 术语表为准(见 `business-terminology.md`):说人话是不拿行话包装,不是把术语表里的词换成别名。