38 lines
1.3 KiB
Markdown
38 lines
1.3 KiB
Markdown
# DOC-017 统一术语与展示记法
|
|
|
|
分类：表述与证据。级别：核心。本规则是项目写作约定，不是语言语义。
|
|
|
|
## 规则
|
|
|
|
同一概念使用同一术语，源码、结果、归属和结构示意使用可区分的记法。
|
|
|
|
## 原因
|
|
|
|
术语漂移与展示混淆会使读者无法判断看到的是代码还是说明。
|
|
|
|
## 执行方法
|
|
|
|
1. Preflight 和 inflight 保持固定大小写；handle 与显示名分别定义。
|
|
2. 外部 key 写在代码块前，代码块只含对应源码；结果使用 text 或效果说明。
|
|
3. 首次正式使用术语时定义或连接术语表，后文保持一致。
|
|
|
|
## 改写对照
|
|
|
|
问题写法：把 key、文件路径、模块地址混称；在源码内写展示提示符。
|
|
|
|
推荐做法：区分 namespace key 与存储对象键，并明确片段与预期结果。
|
|
|
|
以上是说明写作差异的项目例子，不新增语言能力。
|
|
|
|
## 验收
|
|
|
|
- [ ] 术语与术语表一致。
|
|
- [ ] 源码展示没有混入非源码标签。
|
|
- [ ] 记法适用于从其他页面跳入的读者。
|
|
|
|
## 依据与边界
|
|
|
|
[SRC-08](../research/SRC-08.md)、[SRC-15](../research/SRC-15.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。
|
|
|
|
[规则索引](../README.md#规则索引) · [检查清单](../checklist.md)
|