把知识写清楚：语言、风格、示例与图表

让文字指出具体对象与关系复制锚点链接

确定了知识组织与理解路径，起草时要把其中的对象、动作、原因与条件写进具体句子。读者应能辨认谁做了什么、产生什么结果，以及这个结果怎样接到后续解释。空泛评价与模糊指代容易把这些关系隐藏起来。

例如，下面的构造文本要解释一项审稿要求：“提升引用规范性，增强论证可信度。”可展开为：“在关键判断旁标明实际支持它的来源及章节，说明该材料的对象和条件。读者由此可以核对材料是否支持当前结论。”后一句提供了动作、对象与作用，也没有把引用齐全承诺为事实必然正确。

同一对象使用稳定名称。需要简称时，首次关联全名与简称；正文、例子和图中的名称也应对应。陌生术语在首次承担解释或推理时，就地说明够用的含义与作用。Google 的词语指导强调陌生术语定义、名称一致和明确指代；具体用语仍由当前语言与读者基础决定。¹

拆句之后重新检查量词、条件和逻辑。例如，“在样本满足条件时，方法产生预期结果”拆成“样本满足条件。方法产生预期结果”，就改变了假设与结果的关系。简洁可以通过去掉离题和无作用的复述取得，影响结论的限定需要保留。

一段文字完成一个连贯的解释任务复制锚点链接

段落可以说明对象、建立一个关系、解释一个判断，或讨论一个条件变化。围绕当前关注点，将答案、理由和影响它的条件集中起来。跨段承接时，让上一段建立的信息成为下一段的起点。

引用放在它实际支持的主张附近。来源提供数据，正文解释数据怎样支持判断；多个来源分别支持不同部分，就分别定位。作者建议、原始结果和本篇综合推断也应辨认清楚。研究与证据决定判断能够有多强，起草时把这个强度保留下来。

比如，“某指南推荐这种写法，因此它适合所有文档”，跨过了适用性判断。完整论述还要交代指南服务什么读者与任务，当前文章哪些条件相近，哪些差异仍需处理。原文没有覆盖的范围，不能借引用的形式自动补齐。

出处应能定位到实际读取的材料，按需要保留作者或机构、标题、版本及章节。必要解释在正文中完成；延伸阅读可进一步展开相邻问题。引用数量、来源声誉和长参考文献表，都不能代替论证中的关系。

按读者与用途调整风格复制锚点链接

风格是表达中的可变选择，包括语气、人称、叙事入口、展开节奏、信息密度、示例领域及媒介配合。同一套知识，可以为初次理解、横向比较和快速查阅提供不同的展开方式。选择的依据是当前读者实际需要的知识与结果。

下面仍使用审稿情境，两段均为构造示例，表达同一个要求：

第一种展开了“引用支持什么”和“建议还需要什么”，第二种利用已有知识压缩回顾。高信息密度依赖共同基础；对陌生内容减少字数时，仍要保留理解所需关系。直接表达也可以耐心展开，严谨表达同样可以使用具体情境。

系列文章保持主要称呼和语气一致，局部任务变化时自然过渡。专家读者可以跳过熟悉背景，初学者需要及时得到新对象的解释。是否先给结论、先讲情境或先建立模型，依本篇任务选择；重要条件与证据强度随表达一起保留。

风格调整可以回应具体反馈：读者反复寻找结论，可改善答案定位；读者把两个术语当成不同对象，可统一名称并解释简称；读者不熟悉案例业务，可更换例子。作者偏好和单次好评可以提供线索，实际理解效果需要相应读者证据。

给示例一个明确任务复制锚点链接

一个例子可以建立陌生对象、展示规则变化、连接抽象概念，或暴露模型的边界。先说明它要解释什么，再提供决定结果的前提、输入、规则与结果，最后把个案对应回所讲关系。

例如，上面的引用例子用于说明“来源支持”和“采纳推理”是两个需要相接的部分。它无需补入完整审稿平台和业务流程。换例能更清楚地呈现新关系时，可以换例；机制逐层展开且对象稳定时，可以延续同一个情境。

构造数据、教学模型与预期结果要能识别，真实案例保留实际条件和观察范围。类比也要说明对应关系及重要失效处。把引用比作地址，能够帮助理解定位作用；地址存在并不能保证材料正确，这个失效处恰好提示仍需评价证据。

代码示例要说明必要依赖、输入和预期结果。完整可执行样例需要实际执行证据；展示性片段标明省略内容和验证状态。Google 的代码示例指导要求示例完成声称的任务，并说明运行条件与结果，删减也应保留正确性。² 技术对象、状态和机制怎样逐层解释，见技术讲解。

按信息关系选择图表复制锚点链接

先写明读者要从载体中看出什么，再选择表现方式。Google 的图示指导建议先确定说明要点，使图对应解释目标。³ 一张图若要求读者自行猜测箭头含义，即使外观完整，也还缺少必要解释。

表格适合共同维度下的映射和比较，Google 的表格指南也区分列表与表格的用途。⁴ 长论证塞入单元格，会让推理被碎片化；比较口径不同，则应先调整口径或明确不可比。

图与正文统一名称、方向和结论。复杂图片的关键关系与数据，还需提供可获取的文字表达。W3C WAI 对复杂图建议配合短描述和表达必要信息的长描述；短 alt 负责识别图片，不能独自承载复杂关系。⁵ 颜色可辅助定位，重要区别同时用标签、结构或文字说明。

是否填了 alt、图片是否编译、关系是否准确、页面是否可访问，分别需要对应检查。读者是否看懂图，同样需要相应证据。载体选择服务信息关系，制作多少图表由当前解释需要决定。

按信息作用删改复制锚点链接

修订时辨认每段对主要理解的作用：建立前提、解释关系、提供证据、说明边界，还是帮助定位。合并同一关注点的分散说明，删除没有增加信息的复述和无依据修饰；首次理解需要的前提、跨页承接和图的文字替代按作用保留。

引用、图、段落同时出现相同结论时，判断它们分别承担什么工作。图表达关系，正文指出要点，来源供复核，可以共同存在；反复换词说同一判断且无新作用，就可以收敛。Google 的自编辑指导采用读者视角并建议获取具体审阅意见，这类反馈有助于定位作者熟悉主题后容易略过的断点。⁶

事实、例子或表达关系改变后，回查受影响依据与解释。以“删短了多少”判断修订收益，会忽略必要信息是否丢失。质量与维护进一步说明怎样按缺陷影响决定修订与交付。

Footnotes复制锚点链接

1. Google Technical Writing，Words，Define new or unfamiliar terms、Use terms consistently、Recognize ambiguous pronouns。 ↩

2. Google Technical Writing，Creating sample code，Correct、Running sample code、Concise、Reusable。 ↩

3. Google Technical Writing，Illustrating，Write the caption first、Focus the reader’s attention。本文未采用单图信息数量阈值。 ↩

4. Google developer documentation style guide，Tables，List or table?、Places not to use tables。 ↩

5. W3C WAI，Complex Images，Overview、Long descriptions。 ↩

6. Google Technical Writing，Self-editing，Think like your audience、Find a peer editor。 ↩