技术写作速查表

这是我在审阅文档时经常参考的， 精选自谷歌技术写作课程的摘要列表。 因为我有时会忘记事情。

总则/引言

• 确定你的受众以及他们希望学到什么。
• 文档内容要符合受众需求。
• 介绍文档的范围和任何前提条件。
• 先拟定文档大纲。或者，先自由写作，然后再进行组织。
• 养成持续复习的习惯。
• 在文档开头明确文档的关键要点。
• 审阅文件时，请大声朗读（默读）。
• 找一位优秀的同行编辑。
• 在草稿写完很久之后再回头审阅文档。
• 与读者已经熟悉的事物进行比较和对比。

内容

• 尽量使用以任务为导向的标题。
• 使用术语时要保持一致。
  • 如果在方法执行过程中更改变量名，代码将无法编译。同样地，如果在文档中间重命名术语，你的想法（在用户脑海中）将无法理解。
• 避免使用含义模糊的代词。
• 尽量使用主动语态，而不是被动语态。
  • “Python 解释代码”而不是“代码由 Python 解释”。
• 选择具体的动词，而不是模糊的动词。
• 每句话都只围绕一个中心思想展开。
• 将一些长句子转换为列表。
• 删除不必要的词语。
  • 像simply或just。
• 当顺序很重要时，使用编号列表；当顺序无关紧要时，使用项目符号列表。
• 保持列表项平行。
  • 平行列表中的所有项目看起来都像是“属于”一起的。
• 编号列表项以祈使句开头。
  • “安装它”。
• 适当地引入列表和表格。
• 写出精彩的开头句，确立段落的中心思想。
• 每个段落只围绕一个主题展开。

代码示例

• 在教程中，用例子来巩固概念。
• 编写简洁易懂的示例代码。
• 避免对显而易见的代码添加注释。
• 代码注释要简短，但要注重清晰性而非简洁性。
• 不仅要提供例子，还要提供反例。
• 提供能够展现不同复杂程度的代码示例。
  • 简单和复杂的例子。

图纸

• 考虑在绘制插图之前先写好图注。
• 通过在图片说明中描述要点或在图片中添加视觉提示，将读者的注意力集中在图片或图表的相关部分。

如果您想了解更多相关内容，请查看相关课程。共有两门课程，都非常棒！