38 lines
1.3 KiB
Markdown
38 lines
1.3 KiB
Markdown
# DOC-019 让格式服务理解与查找
|
|
|
|
分类：表述与证据。级别：建议。本规则是项目写作约定，不是语言语义。
|
|
|
|
## 规则
|
|
|
|
按信息关系选择文字、代码、表格或图，避免机械地给每段增加图表。
|
|
|
|
## 原因
|
|
|
|
格式应减少理解成本，而不是证明页面很完整。
|
|
|
|
## 执行方法
|
|
|
|
1. 签名、参数和重复映射适合表格；依赖和树形关系适合小图。
|
|
2. 短定义用段落，步骤用有序列表，源码用标注语言的代码块。
|
|
3. 标题表达实际主题；表格不能代替关键的原因或边界说明。
|
|
|
|
## 改写对照
|
|
|
|
问题写法：单个字段解释也配一张复杂流程图。
|
|
|
|
推荐做法：渲染树用小型结构示意，组件参数用表格，其余直接说明。
|
|
|
|
以上是说明写作差异的项目例子，不新增语言能力。
|
|
|
|
## 验收
|
|
|
|
- [ ] 格式与关系类型匹配。
|
|
- [ ] 源码可复制，结构示意不冒充源码。
|
|
- [ ] Markdown 标题、列表与代码块正确闭合。
|
|
|
|
## 依据与边界
|
|
|
|
[SRC-03](../research/SRC-03.md)、[SRC-06](../research/SRC-06.md)。来源页记录观察与分析，本页的执行方法是针对项目的综合建议，不宣称由某一原文逐项规定。
|
|
|
|
[规则索引](../README.md#规则索引) · [检查清单](../checklist.md)
|