本文翻译自 Google Technical Writing Courses，是Google推出的技术写作课程，该课程包含两个部分，本文是第二部分。
翻译仅供学习使用。由于译者水平有限，本文不免存在遗漏或错误之处。如有疑问，请查阅原文。
以下是译文。
简介
技术写作第二部分帮助技术人员提升他们的技术沟通技巧。
目标受众
这门课程针对那么完成了技术写作第一部分并且仍然渴望学习更多技术写作训练的人。如果你还没有受过任何技术写作训练，我们建议你先完成技术写作第一部分的课程后再来学习这部分内容。
学习目标
本课程侧重于技术写作中的几个中级主题。完成本课程后，你将知道如何做以下事情：
- 选择几种不同的策略来编写初稿，并选择其它策略来编写二稿或三稿。
- 使用多种技术手段来检查自己写作中的错误。
- 组织大型文档。
- 介绍文档的范围和任何预备知识。
- 写清楚图片标题。
- 在技术插图中选择适当的信息密度。
- 将读者的注意力集中在插图上。
- 通过“大图”插图建立上下文。
- 有效修改技术插图。
- 创建有用、准确、简洁、清晰、可复用和注释良好的示例代码，以展示一系列复杂性。
- 识别不同类型的文档。
- 描述几乎所有的事情。
- 对初学者赋有同理心，并为他们编写入门教程。
成为一个杰出的工程师或技术写作者需要多年的专注练习。本课程将会提升你的技术写作技能，但不能立即把你变为一个杰出的技术写作者。
自我编辑
想象一下，你刚刚编写了文档的初稿。你如何做得更好呢？在大部分情况下，达到可最终发布的文档是一个反复迭代的过程。从零到初稿通常是最困难的步骤。在编写完初稿后，确保你能留出大量时间来完善文档。
本单元中的编辑技巧可以帮助你将初稿转变成文档，从而可以更清晰地传达受众所需要的信息。你可以使用其中一个或全部技巧；但重要的是找到适合你的策略，然后将该策略成为你写作日常的一部分。
采用样式指南
公司，组织和大型开源项目的文档经常采用已有风格指南样式或自己写一个指南样式。在 Google Developers 网站上的许多文档都新遵循 《Google 开发者文档样式指南》。如果你之前从未使用过样式指南，乍眼一看，Google 开发者文档样式指南时可能看起来有点吓人，它提供了有关语法、标点、格式和计算机接口文档等主题的详细指南。所以，你可能更喜欢从《样式指南精要》开始。
注意：对于较小的项目，如团队文档或小型开源项目，你会发现《样式指南精要》已经够用了。
精要内容中列表出的一些准则在技术写作一中已经介绍了。你可能会回忆起以下面一些技术：
精要还介绍了其它许多技术，这些技术在编写技术文档时可能会有用，例如：
- 使用第二人称。优先使用“你”而不是“我们”去称呼你的受众。
- 将条件子句放在指令之前，而不是之后。
- 格式化 代码相关文本的代码字体。
像你的受众一样思考
谁是你的受众呢？退一步，试着从他们的角度阅读初稿。确保文档的目的是清晰的，并为读者定义可能不熟悉的任何术语或概念。
为你的受众勾勒出一个角色可能会有帮助。角色可以由以下任何属性组成：
- 角色，例如 系统工程师 或 QA 测试人员。
- 最终目标，例如：还原数据库。
- 一组关一起角色及其知识和经验的假设。例如，你可以假定你的角色是：
- 熟悉 Python。
- 运行Linux操作系统。
- 熟悉命令行操作。
然后，你可以想象你的角色来重新查看你的草稿。告诉受众你所做的任何假设都特别有用。你还可以提供资源链接，以便你的受众在需要复习特定主题时了解更多信息。
注意，过度依赖于角色（或两个角色）可能会导致文档过于狭窄而无法对大多数读者有用。
有关技术写作一的复习和更多信息，请参阅 受众 自学单元
大声朗读
根据上下文或写作风格可能会疏远、吸引甚至让你的受众感到厌烦。给定文档所需的样式在一定程度上取决于你的受众。例如，旨在招募志愿者的新开源项目的贡献者指南可能采用非正式和对话式的风格，而商业企业应用程序的开发者指南可能采用更正式的风格。
要检查你的写作是否是会议式的，请大声朗读。识别尴尬的措辞、长太的句子或其它任何感觉不自然的内容。另外，考虑使用 屏幕阅读器 为你朗读文档内容。
关于调整写作风格以适应你的受众的更多信息，请参考 样式和作者语气。
稍后再回来
在你完成初稿（二稿或三稿）后，将它放置一边，一个小时（或两到三个小时）后再回来阅读，这样在阅读时会有新鲜感。这样，你几乎总是会注意到一些可以改进的地方。
切换上下文
有些写作者喜欢打印出他们的文档，并且手里拿一支红色铅笔，审查纸质文档副本。这种换一种场景来审视自己的作品时，可以帮忙你找到需要改进的地方。对于这个经典技术的现代化诠释，你可以将草稿复制到不同的文档中，并更改字体、大小和颜色。
寻找同伴编辑
如同工程师需要同行来审查他们的代码一样，作家也需要编辑来给他们关于文档的反馈。请他人来审阅你的作品，并给你具体的建设性意见。你的同行编辑不必是文档技术主题的主题专家，但他们确实需要熟悉你遵循的样式指南。
组织大型文档
你如何将大量的信息组织成一个连贯的文档或网站呢？或者说，你如何将当前杂乱的文档或网站重组成通俗易懂的东西？以下策略可以帮助你：
- 选择编写单个大文档或一组文档
- 整理组织文档
- 添加导航
- 逐步展开信息
何时编写大型文档
你可以将一组信息组织成较长的独立文档或一组较短的相关文档。一组较短的相关文档通常以网站、wiki或类似的结构格式发布。
有些读者更喜欢阅读长文档。考虑你编写的文档面向的以下两个假设的读者视角：
- Hong 发现阅读长文档很困难并且容易迷失方向。他更喜欢使用站点来搜索答案。
- Rose 很擅长浏览大型文档。她经常使用浏览器中内置的页面搜索功能来查找当前页面上有用的信息。
那么，你应该将材料组织成单个文档还是网站中的一组文档呢？考虑以下准则：
- 对于新手而言，How-to 操作指南，入门简介和概念指南通常以较短的文档展示时会更友好。例如，一个对文档完全陌生的读者，可能很难记住很多新的术语、概念和事实。请记住，你的受众可能是想通过你的文档快速了解该主题。
- 深入的教程、最佳实践指南和命令行参考页以长文档方式可能比较好，特别是在面向有对那么工具和主题有一定经验的读者。
- 一个出色的教程可以依靠叙述来引导读者完成较长文档中的一系列相关任务。然而，即使是大型教程，很多时候分割成较小的部分会更好。
- 许多长文档并非旨在一次性阅读。例如，用户通常浏览参考手册以搜索命令或参数的解释。
本单元其余部分介绍关于编写长文档的方法，例如教程和一些概念性指南的有用信息。
组织文档
本节提出了一些规划长文档的技巧，包括创建大纲和起草简介。在完成文档的初稿后，根据大纲和简介进行复审，以确保你没有遗漏任何本打算涵盖的内容。
文档大纲
从结构化的高层级的大纲开始，可以帮助你对相关主题进行分组并确定哪里需要更多详细信息。大纲可以帮助你在开始写作前先讨论主题。
你可能会发现将大纲视为文档的叙述很有用。对于编写大纲，没有标准的方法，但是下面指南提供的实用技术或许对你有所帮助：
- 在要求读者执行任务之前，请向他们解释为什么要执行这个任务。例如，以下要点说明了教程中有关审核和改进网页可访问性的部大纲：
- 介绍审核网页可访问性的浏览器插件；说明读者将使用审计报告的结果来修复一些错误。
- 列出运行插件和审计网页可访问性的步骤。
- 将大纲的每个步骤限制为描述概念和完成特定任务。
- 结构化你的大纲，以便你的文档在与读者最相关时介绍信息。例如，当你的读者刚开始使用基础知识时，他们可能并不需要在文档的简介部分了解（或想要了解）项目的历史。如果你觉得项目的历史很有用，请在文档末尾添加指向此类信息的链接。
- 考虑解释一个概念，然后向读者展示如何在示例项目或他们自己的工作中应用它。在概念信息和实际步骤之间交替的文档可能是一种特别吸引人的学习方式。
- 在开始起草之前，请将你的大纲与贡献者分享。如果你正在与一个将要审阅和测试文档的贡献者团队合作，那么大纲尤其有用。
大纲练习
查看并更新以下长教程简介的高层级大纲。要解决此练习，你可以执行以下任何操作：
- 重新排列现有主题。
- 添加任何你认为在简介中缺失的主题。
- 移除任何你认为在简单中多余的主题。
1 | ## 项目的历史 |
介绍文档
如果文档的读者找不到与主题相关的内容，则他们基本上会忽略这个文档。要为你的用户设置基本规则，我们建议提供包含以下信息的介绍：
- 文档覆盖的内容。
- 你期望读者具备哪些先决知识。
- 文档未覆盖的内容。
请记住，你想使文档易于维护，因此请勿尝试在简介中介绍所有内容。
下面段落展示了上面列表中的思想，作为一个名为Froobus文档发布平台的假设文档概述：
This document explains how to publish Markdown files using the Froobus system.
Froobus is a publishing system that runs on a Linux server and converts
Markdown files into HTML pages. This document is intended for people who are
familiar with Markdown syntax. To learn about the syntax, see the Markdown
reference. You also need to be comfortable running simple commands in a
Linux terminal. This document doesn’t include information about installing or
configuring a Froobus publishing system. For information on installing Froobus,
see Getting started.本文档说明了如何使用Froobus系统发布Markdown文件。
Froobus是一个运行在Linux服务器上的将Markdown文件转成HTML页面的发布系统。
本文档适用于熟悉Markdown语法。要了解Markdown语法，请参考 Markdown。你还需要了解在Linux终端下的一些命令。
本文档不包含有关安装或配置Froobus发布系统的内容。有关Froobus的安装，请参考Froobus使用入门手册。
完成初稿后，根据你在概述中设定的期望检查整个文档。你的简介是否提供你所覆盖的主题的准确概述？你可能会发现将审阅作为文档的质量保证（QA)一种形式是很有用的。
介绍练习
对于本练习，请查看并修改以下介绍，以获取一种称为F@的假设编程语言的最佳实践指南。删除你认为与此无关的任何信息，并添加你认为缺乏的任何信息。
This guide lists best practices for working with the F@ programming language.
F@ was developed in 2011 as an open source community project. This guide
supplements the F@ style guide. In addition to the best practices in this guide,
make sure you also install the F@ command-line linter and run it on your code.
The programming language is widely adopted in the health industry. If you have
suggestions for additions to the list of best practices, file an issue in the
F@ documentation repository.本指南列出了使用F@编程语言的最佳实践。
F@ 是2011年开发的一个开源社区项目。本指南提供了F@的代码风格指南。除了本指南中的最佳实践，确保你还已安装并运行F@命令行Linter。该编程语言在健康行业中被广泛采用。如果你有关于最佳实践列表的补充建议，请到F@的代码库上给我们提issue。
添加导航
为你的读者提供导航和路标，以确保他们可以找到他们正在寻找的内容以及需要的内容而不至于陷入困境。
清晰的导航包括：
- 简介和总结部分
- 一个清晰有逻辑的主题
- 有助于用户理解主题的标题和副标题
- 目录菜单，向用户展示他们在文档中的位置
- 链接到相关资源或更深入的信息
- 链接到下一步学习
以下各节中的技巧可以帮助你规划文档的标题。
首先基于任务的标题
选择描述你的读者正在从事的任务的标题。避免使用不熟悉的术语或工具的标题。例如，你正在编写创建新网站的过程，要创建站点，读者必须初始化Froobus框架。要初始化Froobus框架，必须运行carambola命令行工具。乍眼一看，在说明中添加以下任一标题是合乎逻辑的：
- 运行 caramabola 命令
- 初始化 Froobus 框架
除非你的读者已经非常熟悉该主题的术语和概念，否则最好使用更熟悉的标题，例如“创建站点”。
在标题下提供文字
大多数读者都喜欢在每个标题下至少有一个简短的介绍，以提供一些背景信息。避免在二级标题之后立即放置三级标题，如下所示：
1 | ## 创建站点 |
在这个示例中，简要介绍可以帮助读者确定方向：
1 | ## 创建站点 |
标题练习
帮助读者浏览你的文档大纲可以帮助他们通过成功使用你的工具找到所需的信息。通常，一个清晰，组织有条理的目录或大纲就像一个地图一样，可以帮助你的用户浏览你的工具的功能。
对于本练习，请改进以下大纲。你可以重新排列、添加和删除主题，也可以创建辅助条目。
1 | 关于本教程 |
逐步展开
对于许多喜欢按照自己的节奏阅读文档的读者来说，学习新概念、想法和技术可能是一种有益的体验。但是，过快的面对太多的新概念和指令可能会让人不知所措。读者很有可能接受较长文档的形式是，这些文档会在他们需要的时候逐步向他们展开信息。以上技术可以帮助你在文档中逐步展示信息：
- 尽可能地，在需要用到的地方引入新的术语和概念。
- 分解大段方案。为了避免在一个页面上出现多个较大的段落，请在适当的地方引入表格，图表，列表和标题。
- 分解大量步骤。如果你有一个特别长的复杂步骤，请尝试将它们重新排列成较短的列表，以解释如何完成子任务。
- 从简单的示例和说明开始，然后逐步添加更多有趣和复杂的技术。例如，在创建表单的教程中，首先说明如何处理文本响应，然后介绍其它技术来处理多个选择，图像和其它影响类型。
插图
还记得你的老师给你分配了一个厚重的章节来阅读吗？你翻阅了教科书的指定部分，迫切地希望…是的，图片！查看插图比阅读文本有趣得多。实际上，在阅读技术资料时，绝大多数成年人仍然是小孩子，他们仍然渴望图片而不是文字。
Figure 1. Good graphics engage readers in ways that text cannot.
Nirmal Dulal [CC BY-SA 4.0 (https://creativecommons.org/licenses/by-sa/4.0)]
根据 Sung and Mayer(2012)的研究，提供任何图片（无论好坏）都会使读者更喜欢该文档。但是，只有指导性的图片才能帮助读者学习。本单元提供了几种方法来帮助你创建一图胜千言的图片。
先写标题
通常，在创建插图前写标题会很有帮助。然后，创建最能说明标题的插图，这个过程可以帮助你检查插图是否和目标吻合。
好的标题具有以下特征：
- 他们很 简短。通常，标题只有几个单词。
- 他们解释了 要点。查看此图片后，读者应该记住什么？
- 他们 聚集 读者的注意力。当图片或图表包含很多细节时，聚集尤其重要。
注意：按照惯例，标题问题跟在图表后面。
示例
目标受众：学习了“数据结构入门”课程的CS本科生。
考虑以下三个图片，每个图片使用了相同的标题。
标题A。单向链表包含内容和指向下一个节点的指针。
标题B。单向链表包含内容和指向下一个节点的指针。
标题C。单向链表包含内容和指向下一个节点的指针。
上面三个图中哪个最能说明其标题呢？
- 图A比较糟糕。链表很漂亮，但是没有信息。链中还错误地暗示了单链表既指向后，又指向前。
- 图B是可以的。这个插图帮助学生认识到第一项指向第二项，第二项指向第三项，以此类推。但是，虽然标题同时引用了内容和指针，但是插图仅展示了指针，但没有展示内容。
- 图C是最好、最有启发意义的选择。插图清楚地描述了每个节点的内容部分和指针部分。
限制单个图中的信息量
很少有智力工作可以像学习一幅精美的画作一样有益，逐渐揭示了洞察力和意义。人们在世界艺术博物馆中付出了很多钱来做到这一点。
Figure 2. 你会很高兴研究梵高的这幅画。
Portrait of Pere Tanguy By Vincent van Gogh - Musée Rodin [Public domain]
相比之下，像下面所求中的高度复杂的技术插图往往会让大多数读者望而却步：
Figure 3. 复杂的框图让读者望而却步。
就像你避免过长的句子一样，也要努力避免视觉上的太多信息。作为经验，不要将超过一个段落的信息放在一个图表中。（另一种经验法则是避免需要超过五个项目符号的项目来解释的插图。）我听到你说：“但是，现实生活中的技术系统可能比较图3中显示的复杂得多。”你是对的，但是你可能没有必要在单个段落中解释这个复杂的系统。
将视觉混乱转变成连贯且有用的诀窍是将复杂的系统组织成子系统，如下图所示：
Figure 4. 分为三个子系统的复杂系统。
显示“大图”之后，分别提供每个子系统的图示：
Figure 5. 复杂系统的一个子系统展开细节。
另外，可以从简单的“大图”开始，然后在每个后续插图中逐步展开细节。
集中读者的注意力
面对如下复杂的屏幕截图时，读者很难确定它们之间的相关性：
Figure 6. 读者不知道该关注什么。
添加视觉提示，例如下图中红色椭圆，可以帮助读者专注于屏幕截图的相关部分：
Figure 7. 读者关注打破模式的形状。
标注提供了另一种吸引读者注意力的方式。对于图片和线条艺术，标注可以帮助我们的眼睛找到正确的着陆点。图片中的标注通常比对图片的长段解释更好，因为标注将读者的注意力集中在图片最重要的方面。然后，在你的解释中，你可以直接关注图表的相关部分，而不是花时间描述你正在讨论图像的哪一部分。
在示例图像中，标注和箭头快速将读者引导至目标。
Figure 8. 标注引导读者的视线。
NASA / JPL-Caltech / University of Arizona [Public domain]
插图重构
与写作一样，插图的初稿很少足够好。修改你的插图以阐明内容。修改时，请问自己以下问题：
- 如何简化插图？
- 我应该将该插图拆分成两个或更多个简单的插图吗？
- 插图的文字是否易于阅读？文本与背景是否有充分对比？
- 要点是什么？
例如，考虑 伦敦地铁图的演变。在1931年之前，地铁地图是按比例绘制的，包括地上道路和与轨道一样弯曲的地铁线路。
Figure 9. 1908年按地面街道绘制的伦敦地铁地图。
1931年，哈里·贝克（Harry Bech）开创了一种新型的公共交通地图，通过取消地面标记和比例尺来简化旧地图。他的设计专注于使用地图的人真正关心的事情：从 A 站到 B 站。即使他1931年的地图取得成功，但贝克仍然在地图上迭代多年，以简化和阐明地图。考虑现在的 现代地图，尽管出现了新的线路和车站，但它们仍然与贝克的设计接近。
练习
考虑以下原始插图：
Figure 10. 复杂插图
上图的要点应该是：
对于递归函数，在return语句中调用函数本身，直至获得基本解为止。
图表的复杂性在哪些方面隐藏了要点？你会如何解决这些问题？
该图中可能存在的一些问题包括：
- 问题：鲜艳的颜色将读者的注意力从图表的其它方面转移开。
解决方案：仔细选择颜色，以免它们压倒图表。
- 问题：该图没有足够的色彩对比度。这使得某些视力低下或某些类型的色盲的人无法看清该图表。
解决方案：移除不必要的颜色使用，并确保颜色符合 标准颜色对比建议。
- 问题：箭头指向两个方向，这使得图的流向变得不清楚。
解决方案：将箭头分为两个部分，其中一组说明调用功能，另一组说明从功能返回。当然，图中还有其它未在这里指出的问题。
这是一个改进的图示：
Figure 11. 上图的简化版本。
你在改进的插图中看到哪些缺陷？
这里仍然存在两个缺陷：
- 该图仍然太复杂。要解释此插图，需要的不仅仅是段落。考虑删除多余的信息或添加说明标签来简化解释。
- 虽然分隔箭头有助于在函数调用或返回数据时显示，但返回箭头可能受益于告诉读者返回值是什么的标签。
插图工具
有许多工具可以用于创建表格。这里推荐三个免费的作图工具：
从这些工具导出图表供文档使用时，通常最好将文件导出为 Scalable Vector Graphics（SVG）。SVG 可以根据空间限制轻松缩放图表，因此无论大小如何，你最终都会获得高质量的图像。
示例代码
好的示例代码通常是最好的文档。即使你的段落和列表像水一样清澈，程序员仍然更喜欢好的示例代码。毕竟，文本与代码是不同的语言，并且读者最终关心的是代码。试图用文本描述代码，就像试图用英语解释一首意大利诗歌一样。
好的示例是 正确且简洁的代码，你的读者可以快速理解，轻松重用，并且副作用最小。
正确
示例代码应该满足以下条件：
- 构建没有错误。
- 能够执行它应该完成的任务。
- 尽可能是可以上生产线的代码。例如，该代码不包含任何安全漏洞。
- 遵循特定语言的规范。
示例代码直接影响用户编写代码的方式。因此，示例代码应该示例最佳的编码方式。如果编码的方式不止一种，请以你的团队认为最好的方式对其进行编码。如果你的团队还没有考虑每种方法的利弊，请花一些时间去对比各个方式的优缺点。
始终测试你的示例代码。随着时间的流逝，系统会发生变化，示例代码也可能会出错。与其它任何代码一样，测试并维护你的示例代码。
许多团队用单元测试作为示例代码，这有时是个坏主意。因为，单元测试的主要目的是测试，而示例代码的最终目的是教育。
一个程序片段是示例程序的一部分，可能只有一行或几行代码长。这种包含大量程序片段的文档通常会随着时间的推移而退化，因为团队倾向于不像完整示例那样严格地测试程序片段。
运行示例代码
好的文档说明如何运行示例代码。例如，在运行示例代码之前，你的文档可能需要告诉用户执行以下活动：
- 安装某个库。
- 配置某些环境变量的值。
- 配置集成开发环境（IDE）。
用户并不总是能正确执行上述活动。在某些情况下，用户喜欢直接在文档中运行或（使用）示例代码。（如：”单击此处运行代码。“）
编写者应考虑描述示例代码的预期输出或结果，尤其是对于难以运行的示例代码。
简洁
示例代码应该简短，仅包括基本组件。当一个C语言新手想学习如何调用 malloc 函数时，请给他一个简短的代码片段，而不是整个Linux源代码树。不相关的代码可能会分散受众的注意力并让他们感到困惑。也就是说，永远不要使用错误的做法来缩短代码；总是优先使用正确性而不是简洁性。
易理解
请遵循下列建议来创建清晰的示例代码：
- 选择自描述性的类，方法和变量名。
- 避免使用让读者难以理解的编程技巧。
- 避免深层嵌套的代码。
- 可选的：使用粗体或彩色体将读者注意力吸引到代码的特定部分。但是，应该明智地使用突出显示，过多的突出显示意味着读者不会特别关注任何内容。
注释
考虑以面关于示例代码注释的推荐做法：
- 保持简短，但是清晰高于简洁。
- 避免编写明显的代码注释，但是请记住，对你（专家）而言简单的东西对新手可能并不明显。
- 将你的评论精力集中在代码中任何不直观的地方
- 当你的读者对这项技术非常有经验，不要解释代码是什么，解释代码为什么这么干。
你应该将代码描述放在代码注释中还是放在示例代码之外（段落或列表）呢？请注意，复制粘贴片段的读者不仅会收集代码，还会收集任何嵌入的注释。因此，将代码描述放入代码注释中，以便可以一同复杂粘贴。相反，当你必须解释一个冗长或难以理解的概念时，通常应该将注释文本放在示例程序之前。
注：如果为了使代码更简短且更易于理解，而必须牺牲能够上生产环境，请在注释中解释你的决定。
可重用
为了使读者能够轻松复用你的示例代码，请提供以下内容：
- 运行示例代码所需的所有信息，包括所有依赖关系和设置。
- 可以以有用的方式扩展或定制代码。
拥有易于理解的简洁且可编译的示例代码是一个很好的开始。但是，如果毁了读者的应用程序，他们将不会高兴。因此，在编写示例代码时，请考虑将代码集成到另一个程序中导致的任何潜在副作用。没有人想要不安全或效率极低的代码。
正反示例
除了告诉读者要做什么之外，有时还要明智地向读者展示不应该做什么。例如，许多编程语言都允许程序员在等号的两侧放置空格。现在，假设你正在使用某种语言（例如bash）编写教程，该语言不允许在等号两侧放置空格。在这种情况下，同时展示好例子和反面例子将使读者受益。例如：
正确的示例
1 | # A valid string assignment. |
错误的示例
1 | # An invalid string assignment because of the white space on either side of the |
序列性
好的示例代码集展示一系列的复杂度。
完全不了解某种技术的读者通常渴望简单的示例来入门。第一个，也是最基本的示例代码通常称为 Hello World程序。掌握基础知识后，工程师们想要更复杂的程序。一组好的示例代码提供了一系列简单、适中和复杂的示例程序。
总结
技术写作二涵盖了以下技术写作的中级课程：
- 采用统一样式。
- 换位思考。
- 大声朗读文档（对自己）。
- 写好初稿后，离开一会儿再回来查看文档。
- 找一个好的同行编辑。
- 文档大纲。或者先写下类别，然后再组织起来。
- 介绍文档的范围和所有先决条件。
- 首选基于任务的标题。
- 循序渐进（在某些情况下）。
- 在创建插图之前，请考虑写标题。
- 将信息限制在一个图示中。
- 通过标注来吸引读者的注意力。
- 创建简单易懂的示例代码。
- 保持代码注释简洁，但首选清晰而不是简洁。
- 避免编写显而易见的代码注释。
- 将你的注释集中在任何不直观的代码上。
- 不仅提供正面示例，还提供反面示例。
- 提供一系列复杂度的代码示例。
- 养成不断修改的习惯。
- 为不同类别的用户提供不同的文档类型。
- 与读者已经熟悉的东西进行比较和对比。
- 在教程中，通过示例来增强概念。
- 在教程中，提出读者可能遇到的问题。
如果时间允许，请考虑查看这些额外的技术写作资源。