技术写作检查清单

繁琐内容

• 繁琐的过渡是否被移除？（“值得注意的是，” “他们为什么这么做？” “我们来看看如何解决这个问题。”）有时，它们对于流畅性是必要的，但大多数情况下可以移除。“值得注意的是”是技术写作中最常用的短语。不要使用它。
• 如果某事重要，解释它为何重要。你的解释应足够有说服力，以使主题显得显而易见。
• 是否有任何琐碎信息可以被移除？
• 是否有任何没有强调核心思想的重复句子？从不同角度重复核心思想是可以的，但非核心思想不应重复。
• 有任何冗余单词或冗余句子吗？
• 避免写任何听起来像宣传的内容。一般来说，以下单词和短语不应使用，因为它们是主观的，无法传达可衡量、有用或可操作的信息：
  • “新颖的”
  • “创新的”
  • “释放”
  • “突破性”
  • “颠覆性的”
  • “开创性的”
  • “具有颠覆性的”
  • “可扩展的”
  • “赋权的”
  • “采纳”
  • “打开可能性”
  • “无与伦比的”
  • “创造机会”
  • “变革性的”
  • “揭示”
  • “有远见的”
  • “开创性的”
  • “有潜力”
  • “引领”
  • “受尊敬的”
  • “雄心勃勃的”
  • “蓬勃发展的”
  • “尖端的”
• 消除销售性质的语言。这是对读者时间的浪费。

有说服力的例子

• 文章能否通过有用且引人注目的例子获益？一个引人注目的例子无需展示步骤就解释了算法。例如：divWadUp(2,3) → 0.66667, divWadDown(2,3) → 0.66666
• 尽可能添加现实世界的例子。
• 在可行的情况下，提供设计决策的历史背景。
• 抽象概念需要大量例子来清晰解释。提供足够的例子，以便读者能够在脑海中形成模式。

改进措辞

• 能否在不丢失信息的情况下缩短句子？
• 能否将一个句子拆分为两个句子？
• 句子中的从句数量能否减少？

提供事实背景

• 信息是否有动机（即，为什么我应该关心）？
• 是否有类似的信息，作家可以进行类比？
• 作家是否展示了一个呈现的事实与当前主题的关系？

引用和其他教程

• 文章是否有至少一个独特的见解，还是在重复已有的内容？为个人利益总结他人的工作是可以的，但对其他人没有帮助。你在文档不足的问题上挣扎得越多，其他读者会越感激你。
• 如果文章借用了其他解释或例子，是否进行了引用？

文章流畅性和标题

• 介绍是否向读者说明了预期的内容？
• 信息依赖是否经过拓扑排序？即，任何假设先前知识的讨论应该在先前知识解释之后进行。
• 需要滚动上下文参考代码或过去的信息吗？阅读者是否可以在大屏幕上不滚动地消化文章？
• 如果讨论的主题存在循环依赖，明确指出你期望读者感到困惑的地方，并告诉他们稍后再看。
• 如果读者只快速浏览标题，他们是否仍能很好地了解发生了什么？糟糕的标题包括“例子”，“第20行”
• 标题是否遵循层次结构？
• 是否有任何缺少标题的主题过渡？
• 段落是否适当地分开，没有文本墙？

目标受众

• 复杂程度/读者水平是否保持一致？
• 不要假设读者需要一会儿教学重入性，接着又期望他们理解以太坊为什么要添加 Blake hash 预编译 。如果你不确定，请尝试写给过去的自己在某个时间点，即三个月前，六个月前，一年前等。

文章内容

• 是否移除了与主题无关的信息，或将其推迟到另一篇文章中？
• 避免在“有趣的离题”上发散，除非它们是有趣或直接有用的。
• 阅读文章后，是否感觉缺少任何重大思想或解释？
• 所有思想必须相互联系。文章中不应有任何无关的信息或没有动机的例子。文章是否解释了所讨论的每个主题之间的关系？

代码块和数学公式

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

• 如果代码旨在被复制和粘贴，读者是否了解运行代码所需的前提条件？

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

• 代码截图是否容易阅读？减少空白并使用大字体？

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

• 代码解释是否给出直观理解或符号执行？不要逐行解释代码。尝试让读者理解发生了什么，以便当他们查看代码时，“一切都能理解”。

• 如果需要引用行号，请截图代码并在图像上标注以引起关注。使用这样的示例：<https://www.rareskills.io/post/uniswap-v2-mint-and-burn>。

• 大型代码块或公式是否具有可视提示以指向重要部分？

• 使用全大写评论以引起注意，并指出希望读者关注的地方。更好的方式是使用截图并注释代码。

• 使较长的代数推导易于跳过或略读。

图表和图像

• 一张图片胜过千言万语；所选的图片是否合适？
• 图像是否有最少的空白（这些会使移动设备上的内容难以阅读）？
• 图像是否可以以可预测的方式阅读（从左到右或从上到下）？
• 使用易于阅读的字体，并确保在移动设备上也能清晰读取。
• 发布时，图像应具有替代文本。
• 如果作品描述某些视觉内容，它应该是视觉化的。

最小化认知负担

• 最小化读者短期记忆中所需的信息量——如有必要，重复过去的信息，如果该信息预计是读者新接触的。
• 避免使读者需要计算货币或脑中计算数学运算。避免使用抽象货币如“代币 A”，用美元价值进行表述。
  • 有没有其他方法可以减少读者的认知负担？
• 使用明显的数字例子。6乘以68不立即显然是408，但6乘以4立即显然是24。值得在例子中调整值，直到所有表示的值呈现得非常明确的数字关系。
• 变量和其他代码对象应采用代码格式化。
• 避免将读者引导至其他页面学习先决知识，除非你为这些主题写了后续内容。这会迫使读者切换上下文。在文章中总结关键思想。
• 提到文件夹时，后面加上斜杠。例如“在src/目录中，我们可以看到…”

使用反事实和回答问题

• 给出非功能代码的例子有时是有帮助的，如果它解释了代码为什么不工作。
• 是否有主题可以受益于解释达到相同目的的替代方法？
• 有没有什么提出了未答复的问题？
• 是否有任何主题的解释不完整？
• 有时，主题最好通过解释其周围的主题而非主题本身来说明。例如，单独“定点数”的动机很难，而不解释浮点数和整数。
• 抓住机会回答“为什么是这样而不是其他”之类的问题。

术语和定义

• 避免快速连续给读者太多非平常的定义。这会增加认知负担。
• 引入新术语时，简要定义，无论你是否会在之后详细解释。让读者在脑中保留一个他们不了解的新术语会增加认知负担。
• 如果术语不完全是常识，将其作为子标题可能会有所帮助。这样，读者可以向后浏览并轻松找到它，如果他们忘记了。
• 对于关键术语和定义，避免使用同义词。重复使用相同的术语，以便对读者明确你所指的内容。

如何作为审稿人给出好的反馈

• 指出不明确的地方，但在你认为理解作家的情况下，写下你认为作家所说的内容。这将给作家反馈，说明读者如何解读他们的话。
• 如果一个例子是引人注目的或有帮助的，指出这一点，以防作家稍后删除它。
• 如果你理解某件事但努力理解（即需要多次阅读），请指出。目标是让阅读变得轻松。“我难以理解”并不是能力不足的承认。
• 大声阅读文章，你会因此发现更多问题。
• 在审稿过程中不要过早给出措辞或拼写的反馈。首先关注高层次的反馈。理想情况下，首轮反馈应高到不直接评论文档。
• 从Grammarly或聊天机器人等工具复述反馈是没用的，除了在写作过程的最后阶段。关注你作为读者的反馈。
• 迅速谷歌搜索该主题并要求聊天机器人就同一主题撰写文章。如果相关文章没有提供任何新见解，请告诉作家。这是你能够给予的最有价值反馈。

准备技术文章

• 写下目标受众已经知道的内容。
• 写下他们为什么想阅读你的文章。
• 写下你想要涵盖的主要思想。
• 列出该主题上现有的文章，以及你认为你的文章会提供附加价值的原因。
• 写下任何曾对你或你所讲解该主题的人感到特别困惑的概念。
• 列出你将创建的图像和图表，以围绕它们规划你的写作。

最初发布于2024年3月25日

• 原文链接： rareskills.io/post/techn...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～