1.6 KiB
1.6 KiB
DOC-017 统一术语与展示记法
分类：表述与证据。级别：核心。本规则是项目写作约定，不是语言语义。
规则
同一概念使用同一术语，源码、结果、归属和结构示意使用可区分的记法。
原因
术语漂移与展示混淆会使读者无法判断看到的是代码还是说明。
执行方法
- Preflight 和 inflight 保持固定大小写；handle 与显示名分别定义。
- 外部 key 写在代码块前，代码块只含对应源码；结果使用 text 或效果说明。
- 首次正式使用术语时定义或连接术语表，后文保持一致。
改写对照
问题写法：把 key、文件路径、模块地址混称；在源码内写展示提示符。
推荐做法：区分 namespace key 与存储对象键，并明确片段与预期结果。
以上是说明写作差异的项目例子，不新增语言能力。
验收
- 术语与术语表一致。
- 源码展示没有混入非源码标签。
- 记法适用于从其他页面跳入的读者。
具体应用
检查正文、源码、标题、表格、链接文字和结果说明中的同一词。源码大小写与符号不能被中文排版替换；简称不自动成为正式更名请求。