冗余内容

• 是否删除了冗余的过渡句？（例如“值得注意的是”、“他们为什么这样做？”、“这里是我们如何解决这个问题的方法。”）有时候它们对于行文流畅是必要的，但大多数都可以删除。“值得注意的是（It is important to note）”是技术写作中被滥用得最多的短语。请不要使用它。
• 如果某件事很重要，请解释它为什么重要。你的解释应该具有足够的说服力，让该主题的重要性变得_显而易见_。
• 是否有任何可以删除的无关紧要的信息？
• 是否有任何未强调核心观点却被重复的句子？从不同角度重复核心观点是可以的，但不应重复非核心观点。
• 是否有任何废话词汇或冗长无用的句子？
• 避免写任何听起来像推销的内容。通常，不应使用以下词语和短语，因为它们具有主观性，且无法传达可衡量、有用或可操作的信息：
  • “novel”（新颖的）
  • “innovative”（创新的）
  • “unleash”（释放）
  • “breakthrough”（突破性的）
  • “game-changing”（改变游戏规则的）
  • “pioneering”（开创性的）
  • “disruptive”（颠覆性的）
  • “scalable”（可扩展的）
  • “empowering”（赋能）
  • “adoption”（广泛采用）
  • “opens up possibilities”（开启无限可能）
  • “unparalleled”（无与伦比的）
  • “creates opportunities”（创造机遇）
  • “transformative”（变革性的）
  • “unveiling”（揭秘）
  • “visionary”（有远见的）
  • “groundbreaking”（开创先河的）
  • “has potential”（具有潜力的）
  • “spearhead”（带头/先锋）
  • “esteemed”（受人尊敬的）
  • “ambitious”（雄心勃勃的）
  • “thriving”（繁荣的）
  • “cutting-edge”（尖端的）
• 消除推销式语言。这是在浪费读者的时间。

具有说服力的示例

• 这篇文章是否能从有帮助且具说服力的示例中受益？一个有说服力的示例能够在不展示步骤的情况下解释算法。例如：divWadUp(2,3) → 0.66667, divWadDown(2,3) → 0.66666
• 尽可能添加现实世界中的示例。
• 在可行的情况下，为设计决策提供历史背景。
• 抽象概念需要大量示例才能解释清楚。请提供足够的示例，以便读者在脑海中形成模式。

措辞优化

• 是否可以在不丢失信息的情况下缩短句子？
• 可以把一个长句拆分成两句吗？
• 可以减少句子中从句的数量吗？

为事实提供上下文

• 信息是否有其动机（即，我为什么要关心这个）？
• 作者是否可以引用非常相似的事实来进行类比？
• 作者是否展示了所提出的事实与当前主题之间的关联？

引用与其他教程

• 这篇文章是否至少包含一个独特的见解，还是仅仅在重述已有的内容？为了个人利益总结他人的工作是可以的，但这并不能帮助到其他人。你在一个缺乏文档记录的问题上挣扎得越多，其他读者就会越感激你。
• 如果文章借鉴了其他的解释或示例，是否进行了引用？

文章连贯性与标题

• 导言是否告诉读者可以从这篇文章中期待什么？
• 信息的依赖关系是否进行了拓扑排序？也就是说，任何假设具有先验知识的讨论，都应出现在先验知识被解释之后。
• 引用代码或之前的信息时，是否需要读者上下滚动页面？读者在大屏幕上阅读时，能否在不向上滚动的情况下消化文章内容？
• 如果讨论的主题中存在循环依赖，请明确指出你预计读者会在哪里感到困惑，并告诉他们等待后面的章节。
• 如果读者只略读标题，他们还能清楚地了解文章讲了什么吗？糟糕的标题包括“示例”、“第 20 行”等。
• 标题是否遵循层级结构？
• 是否有任何缺乏标题的主题过渡？
• 段落划分是否恰当，是否存在密密麻麻的文字墙？

目标受众

• 复杂程度/读者水平是否保持一致？
• 不要假设读者这一刻需要你教什么是重入，下一刻又指望他们能理解 Ethereum 为什么添加 Blake hash 预编译。如果你不确定，试着写给过去某个时间点的自己，比如 3 个月前、6 个月前、一年前等。

文章内容

• 跑题的信息是否被删除或推迟到了另一篇文章中？
• 避免偏离主题去讲“有趣的题外话”，除非它们具有娱乐性或直接有用。
• 读完文章后，是否感觉缺失了任何主要观点或解释？
• 所有的观点必须紧密结合。不应该有任何跑题的信息或毫无动机的示例。文章是否解释了讨论的每个主题是如何相互关联的？

代码块与数学公式

• 如果适用的话，代码是否易于复制和粘贴？

• 如果代码旨在被复制和粘贴，是否告知了读者使代码正常运行所需的必要先决条件？

• 如果代码不打算被复制和粘贴，通常使用截图会更好。

• 代码截图易于阅读吗？是否减少了留白并使用了大字体？

• 如果程序执行有预期输出，是否有输出的截图？

• 代码解释是否提供了直观理解或象征性执行？请勿逐行解释代码。试着让读者理解正在发生的事情，这样当他们看代码时，就会觉得“一切都说得通”。

• 如果需要引用行号，请对代码进行截图并在图像上绘制标记以引起注意。可以参考此示例：https://www.rareskills.io/post/uniswap-v2-mint-and-burn。

• 大段的代码块或公式是否有视觉提示来指向重要部分？

• 使用全大写注释来吸引读者注意到你希望他们关注的地方。更好的是，使用截图并对代码进行标注。

• 让冗长的代数推导过程易于跳过或略读。

图表与图像

• 一图胜千言；是否包含到了合适的图片？
• 图片中的空白区域是否保持在了最低限度（过多的空白会使内容在移动设备上难以阅读）？
• 图片的阅读顺序是否符合预期（从左到右或从上到下）？
• 在图片中使用易于阅读的字体，并确保它们在移动设备上也能轻松阅读。
• 图片在发布时应该带有替换文本（alt-text）。
• 如果某部分内容描述的是具象的视觉对象，那么它应该被可视化展示。

降低认知负荷

• 尽量减少读者在短期记忆中需要保留的信息量——如果预期该信息对读者来说是新内容，在需要时请重复之前的信息。
• 避免让读者在脑海中转换货币或进行心算。避免使用诸如“token A”这样的抽象货币，请用美元价值来进行说明。
  • 还有没有其他方法可以减少读者的认知负荷？
• 使用显而易见的数值示例。6 乘以 68 等于 408 并不显而易见，但 6 乘以 4 等于 24 则一目了然。在示例中反复调整数值，直到所有展示的数值关系都显而易见，这是值得去做的。
• 变量和其他代码对象应该被设为 代码格式。
• 避免引导读者去其他页面学习前置知识，除非你正在写这些主题的后续内容。这会迫使读者切换上下文。请在文章内部总结核心观点。
• 引用文件夹时，在后面加上正斜杠。例如，“在 src/ 目录中我们看到……”

使用反事实与解答问题

• 有时提供无法运行的代码示例会很有帮助，前提是这能解释为什么该代码无法运行。
• 是否有任何主题可以通过解释完成同一件事的替代方案而变得更容易理解？
• 是否引发了任何悬而未决的问题？
• 是否有任何主题的解释不够完整？
• 有时候，与其直接解释主题本身，不如通过解释其周边相关主题来达到最佳的讲解效果。例如，如果不连带解释浮点数和整数，就很难孤立地引出“定点数”的概念。
• 抓住机会回答像“为什么是这样而不是那样”之类的问题。

术语与定义

• 避免向读者连续密集地灌输过多非平凡的定义。这会增加认知负荷。
• 引入新术语时，请对其进行简短定义，即使稍后会详细解释。让读者在脑海中记住一个他们不理解的新术语会增加认知负荷。
• 如果术语不是完全显而易见的，将其作为副标题可能会有所帮助。这样读者如果忘记了，可以向前翻阅并轻松找到。
• 对于核心术语和定义，避免使用同义词。请反复使用相同的术语，以便读者清楚你指的是什么。

作为审稿人如何提供良好的反馈

• 指出表达不清晰的地方，但在那些你_认为_自己理解了作者意图的地方，用你自己的话写下你认为作者在说什么。这将给作者反馈读者是如何解读他们的话语的。
• 如果某个示例具有说服力或很有帮助，请指出来，以免作者日后将其删除。
• 如果你理解了某些内容但很费力（例如需要反复阅读多次），请指出来。我们的目标是使内容易于阅读。“我很难理解”并不是在承认自己能力不足。
• 大声朗读文章。用这种方式你会发现更多的问题。
• 在审查初期，不要对措辞或拼写提出反馈。应首先关注宏观反馈。理想情况下，第一轮反馈应当是从很高层面的审视，而不是直接对文档具体细节进行批注。
• 除了在写作的最后阶段，生搬硬套 Grammarly 或聊天机器人工具的反馈都是无用的。请专注于_你作为读者_的感受来提供反馈。
• 在 Google 上快速搜索一下该主题，并要求聊天机器人写一篇关于同一主题的文章。如果待审阅的文章没有提供任何新颖的见解，请告诉作者。这是你能提供的最有价值的反馈。

准备撰写技术文章

• 写下你的目标受众已经知道的内容。
• 写下他们为什么要读你的文章。
• 写下你想涵盖的主要观点。
• 列出关于该主题的现有文章，并说明为什么你认为你的文章能提供附加价值。
• 写下任何让你或那些你曾向其解释过该主题的人感到特别困惑的概念。
• 列出你要创建的图像和图表，并围绕它们规划你的写作。

首次发布于 2024 年 3 月 25 日