docs

docs — 用浅白语言撰写文档

**你撰写或编辑的每一份文档都必须符合 ISO 24495-1 浅白语言标准。**这不是一种偏好，也不是可以舍弃的团队风格。如果某个句子不符合标准，就要在保存文件前改写。此规则适用于新页面、现有页面的编辑，以及你添加到代码仓库中的任何说明文字：README、指南、教程、参考页面、发行说明、变更日志和文档注释。

目的

ISO 24495-1 是首个浅白语言国际标准。它旨在帮助作者编写读者能够找到、理解并有效使用的文档。

浅白语言的定义

当文档的措辞、结构和设计能帮助目标读者完成以下任务时，该文档就使用了浅白语言：

• 找到所需信息。
• 理解这些信息。
• 使用这些信息实现自己的目的。

四项基本原则

1. 相关性——只纳入读者根据目标和实际情况所需的信息。
2. 易于查找——合理组织内容，让读者快速找到所需信息。
3. 易于理解——使用熟悉的词语、清晰的句子和合乎逻辑的解释。
4. 易于使用——呈现信息，让读者能够据此采取行动或做出决策。

这只是对标准的概述。如需完整指导，请参阅 ISO 24495-1 全文。

流程

浅白语言是一个循环流程，而不是一次性工作：

1. 规划。 确定读者是谁、他们要完成什么任务以及需要什么。明确页面不会涵盖哪些内容。
2. 撰写。 按照上述四项原则起草内容。
3. 评估。 以读者的角度阅读草稿。根据四项原则和下方的自查清单进行检查。在条件允许时，请真实读者使用文档，或自行执行其中的说明。
4. 修改。 修复评估中发现的问题，然后再次评估。

编辑他人的页面时，对你修改的部分执行同样的流程。不要重写已经符合标准的文字。

保存前自查

回答每个问题。如果答案是否定的，就进行修改。

• 相关性。 每个部分是否都有助于读者完成任务？是否删掉了读者不需要的内容？
• 易于查找。 标题是否说明了各部分的内容？读者浏览页面时能否快速找到正确的位置？
• 易于理解。 句子是否简短、主动？每个技术术语是否都在首次使用时得到定义？
• 易于使用。 步骤的顺序是否符合读者实际执行的顺序？读者能否不靠猜测就根据页面采取行动？

浅白语言不是什么

• 它不意味着简化内容。 要保留完整的技术含义，只去除那些对读者毫无益处的难点。
• 它不禁止使用技术术语。 存储文档需要使用“纠删码”和“幂等”这类词语。只需定义一次，之后保持用法一致。
• 它不意味着为了缩短篇幅而牺牲准确性。 准确性优先。如果浅白的表达会导致错误，就使用精确的表述，然后加以解释。
• 它不意味着非正式。 浅白的写作可以很正式，但不能含糊。