43 lines
2.9 KiB
Markdown
43 lines
2.9 KiB
Markdown
# 中文技术表达与记法
|
|
|
|
本页处理会影响理解和检索的表述选择。术语含义以当前主定义为准。
|
|
|
|
## 句子要有对象和可判断的含义
|
|
|
|
先指出对象，再说明职责或行为。用“use 指定依赖的 namespace”代替“这里可以把那边的东西拿过来”。一个段落说明一个主要关系；第二句解释第一句成立的条件或后果。
|
|
|
|
语言文档使用独立陈述。教程中的“你可以”并非错误，但“按我们刚才的讨论”“上面不是说过了吗”依赖聊天背景，应改成具体概念及链接。删去讨好性的评价和无依据的“轻松、自动、强大”。
|
|
|
|
## 定义、规则、理由、例子分别起作用
|
|
|
|
定义回答对象是什么；规则规定合法性与行为；理由解释规则的用途；例子展示一个具体情况。只给比喻不能代替定义，只给代码不能代替行为说明。
|
|
|
|
例如“handle 类似社交平台的 @ 名”可以帮助理解，但仍需明确唯一性、显示名区别及其在 key 中的位置。不能从类比导出 @ 必须写进 key。
|
|
|
|
## 建立有信息量的标题与链接
|
|
|
|
标题使用读者可能搜索的词，如“用户名与显示名”“导入后的名称引用”。链接文字指出目标主题，少用“这里”“详情”。同一页多个“注意事项”应改成各自的边界名称。
|
|
|
|
跨章链接定位真正支持当前断言的页或小节。频繁相互跳转说明正文可能缺少一句局部定义，或章节职责需要重排。
|
|
|
|
## 术语表与源码的边界
|
|
|
|
普通术语第一次出现可给出中文解释和原词。源码名称、key、关键字使用行内代码；阶段名称严格使用 Preflight 与 inflight。展示文字可以使用中文，不能据此把关键字翻译成中文源码。
|
|
|
|
当前正式语言名、源码围栏和 API 大小写保持仓库约定。用户在聊天中使用简称不自动触发全库更名。确需更名时按语义/术语迁移任务核对范围。
|
|
|
|
## 标点和强度
|
|
|
|
中文叙述使用中文标点，源码保留其规定符号。全角冒号不能代替 key 中的半角冒号。中英文混排以可读性保持一致，不要让格式工具改动代码字符串。
|
|
|
|
“必须、不得”须对应明确约束；“建议”表达选择；“例如”不能偷偷定义默认行为。删除“显然”“很容易”等假定读者水平的措辞，直接写出关键理由。
|
|
|
|
## 表格、列表和注释
|
|
|
|
重复字段适合表格，步骤适合有序列表，依赖关系适合小图。连续论证用段落。一个简单关系不必拆成“背景、问题、方案、总结”四个标题。
|
|
|
|
提示框保留会影响例子合法性或结果判断的信息。跨多页相同的设计稿声明保留统一入口；具体未定成员的局部假设仍放在例子旁。
|
|
|
|
[指南改写示例](../examples/EX-01.md) · [DOC-017](../rules/DOC-017.md) · [DOC-018](../rules/DOC-018.md) · [DOC-019](../rules/DOC-019.md)
|
|
|