improve-writing

改进写作

提升书面内容质量的途径。

指南

• 使用正式、中立且专业的语言： 避免使用生动或比喻性的语言。文档应保持平实、简洁，无需刻意写得引人入胜。避免使用口语表达。
• 避免使用破折号和（分）号： 使用直接、主动的表达，避免使用破折号和（分）号。避免使用排比、并列省略、括号插入和同位语结构。
• 列表项标题后使用冒号： 如果列表项中有强调的“标题”词语，应在其后使用冒号，而不是句号。请参考以下列表示例。
• 避免使用项目符号列表： 只有在确实需要列举一组元素时才使用项目符号列表。不要将其作为通用的文本组织方式，用它来代替也可以采用段落组织的内容。
• 有目的地使用强调： 使用强调（粗体、斜体）引导读者阅读文档。强调文本能让读者快速浏览页面时找到重点，在导航和概览中发挥重要作用。
• 优先使用平实的词语： 除非特定技术术语更准确，且这种准确性在上下文中确实重要，否则请使用简单的词语和语言。例如，使用 Send，而不是 dispatch，除非 dispatch 表达了更简单的动词无法传达的信息。
• 不加修饰： 省略不会增加相关含义的修饰性语言。例如 orchestration、pipeline、synergy、first-class、platform-grade 等词。
• 准确使用技术词汇，而非用来炫技： Contract、boundary、observer、layer、primitive、interface 都有特定的工程含义。只有在确实表达这些含义时才使用。如果更平实的词语也适用，应优先使用平实的词语。
• 避免技术术语堆砌： 不要只为增添色彩而使用听起来很酷的词语。如果某个特定术语承载了无法用其他简单方式表达的含义，就使用它，否则请省略。
• 术语保持一致： 文档为某个事物引入名称后，后续不要改用同义词。使用已定义的术语或最简单的替代说法，不要在同一篇文档中另造第三种说法。
• 使用主动语态，以实体为主语： 订阅计划变更时，订阅会发出事件，优于 系统会在订阅计划变更事件发生时发出事件。让执行动作的事物作为句子主语。
• 陈述事实时不要含糊： Might、could、generally、typically 等词不应出现在事实陈述中。如果存在不确定性，应将其列入“待解决问题”或明确标注。如果是事实，就直接陈述。
• 仅在适当时使用分节： 仅在文本内容彼此独立时使用 --- 分隔。不要用它来组织本可用简单标题组织的内容。
• 准确无误： 精确性至关重要。如果使用了具体名称，尤其是使用代码格式（examble）时，该名称必须与源代码完全一致。不得简化，因为名称一旦改变，就不再指向该具体元素。