Python 高手编程系列一千零七十四：7 项技术写作规则

编写良好的文档在许多方面比编写代码更容易。大多数开发人员认为这很难，但通过
遵循一组简单的规则，它会变得非常容易。
我们不是在这里谈论写一本诗集，而是一个全面的文本，可以用来理解一个设计、一
个 API 或任何构成的代码库。
每个开发人员都能够输出这样的材料，本节提供了 7 个规则，可以应用在所有情况下。
● 两步写作：专注于想法，然后审查和塑造你的文本。
● 定位读者：谁会读？
● 使用简单的风格：保持直接和简单。使用好的语法。
● 限制信息范围：一次引入一个概念。
● 使用现实中的代码示例：应避免使用“Foos”和“bars”。
● 使用轻量且充分的方法：你不是在写一本书！
● 使用模板：帮助读者习惯。
这些规则主要来自 AndreasRüping 编写的书 Agile Documentation:A Pattern Guide to
Producing Lightweight Documents for Software Projects，其重点是在软件项目中输出最好的文档。
两步写作
Peter Elbow，在 Writing With Power:Technigues for Mastering the Writing Process 一书中，
解释说，几乎任何人不可能在第一次就写出完美的文本。问题是许多开发人员在编写文档
时尝试直接写出一些完美的文本。他们在这个练习中取得成功的唯一方法是每写两句就停
止写作，然后阅读它们并做一些修正。这意味着他们将重点放在文本的内容和风格上。
这对于大脑来说太难了，结果往往不如预期的那么好。在完全想清楚它的含义之前，
大量的时间和精力花在修正文本的风格和形状。
另一种方法是删除文本的风格和组织，并专注于其内容。所有的想法都写在纸上，不
管它们是怎么写的。开发者开始写一个持续的流，当他或她犯语法错误，或任何东西，只
要不是关于内容的，就不会暂停。例如，如果句子几乎不能理解，只要这些想法被写下来
就没有关系。他或她只是用粗糙的组织写下他想说的话。
通过这种方式，开发者专注于他或她想说什么，并且可能会从他或她的头脑中获得更
多的内容，而不是他或她最初的想法。
做自由写作时的另一个副作用是，与主题没有直接关系的其他想法很容易在头脑中一
闪而过。一个好的做法是当他们出现时将它们写在第二张纸或屏幕上，这样它们就不会丢
失，然后回到当前的写作。
第二步包括回读整个文本并对其进行修正，以便每个人都能理解。修正文本意味着增
强其风格，纠正其错误，重新组织它，并删除任何冗余的信息。
当专门用于编写文档的时间有限时，一个好的做法是将此时间分成两半——一半用于
写作，另一半用于清理和组织文本。
定位读者
当写作内容时，有一个简单的问题，作者应该考虑：谁会读？
这并不总是很明显，因为一个技术文本解释了一个软件如何工作，并且通常为每个可能获取和使用代码的人而写。读者可能是正在寻找问题的合适技术解决方案的研究者或者是需
要利用其实现特性的开发者。架构师也可以从架构的角度来看它是否符合他或她的需求。
好的文档应该遵循一个简单的规则——每个文本都只有一种类型的读者。
这个哲学使写作更容易。作者准确地知道他或她正在面对什么样的读者。他或她可以
提供简明和预先准备的文件，这些文件不是用于所有类型的读者。
一个好的做法是提供一个简短的介绍性文本，在一个句子中解释文档是什么，并指导
读者去读适当的部分。
Atomisator 是一个产品，它提取 RSS 源并将其保存在数据库中，并带有筛选功能。
● 如果你是开发人员，你可能需要查看 API 描述（api.txt）。
● 如果你是管理人员，你可以阅读功能列表和常见问题（features.txt）。
● 如果你是一个架构师，你可以阅读架构和基础设施的说明（arch.txt）。
● 通过这种方式考虑你的读者，你才可能输出更好的文档。
使用简单的风格
Seth Godin 是营销主题中最畅销的图书作者之一。你可能需要阅读 Unleashing the
Ideavirus，你可以在互联网上免费获得（请参阅 http://www.sethgodin.com/ideavirus/downloads/
Ideavirus ReadandShare.pdf）。
前一段时间，他在他的博客上做了一个分析，试图了解为什么他的书卖得这么好。他
列出了营销领域的所有最好的卖家，并比较每个人的每句话的平均词数。
他意识到他的书中每句话的词数最少（13 个词）。这个简单的事实，Seth 解释道，这
证明读者喜欢短而简单的句子，而不是长而漂亮的句子。
通过保持句子短而简单，你的作品将消耗更少的脑力，内容被提取，处理，然后了解。
编写技术文档旨在为读者提供一个软件指南。这不是一个小说故事，应该更像微波炉的通
知那样简短，而不是像最新的斯蒂芬·金的小说。
请记住几个提示。
● 使用简单的句子。它们不应超过两行。
● 每一段最多应由 3 或 4 个句子组成，表达一个主要思想。让你的文本互相呼应。
● 不要重复太多。避免新闻风格，其中的想法一再重复，以确保他们的理解。
● 不要使用几种时态。大多数时候，现在时态是足够的。
● 如果你不是一个真正优秀的作家，不要在文本中讲笑话。在技术文本中滑稽是很难的，很少有作家掌握它。如果你真的想保持一些幽默，把它们放在代码示例中，你
就没事了。
限制信息范围
不好的软件文档有个简单的迹象——你正在寻找一些你知道存在于某处但你找不到的
信息。花了一些时间阅读目录后，你开始尝试通过几个字的组合查询文件，但还是不能得
到你正在寻找的信息。
当作者没有在主题中组织他们的文本时，就会发生这种情况。他们可能提供大量的信
息，但它只是以单一或非逻辑的方式聚集在一起。例如，如果读者正在寻找你的应用程序
的大图片，他或她就不应该阅读 API 文档——这是一个低级的错误。
为了避免这种影响，段落应该被聚集在给定章节的有意义的标题下，全局文档标题应
该用短语来组织内容。
一个目录可以是由所有章节的标题组成。
撰写标题的一个简单做法是问自己：“我在 Google 中输入什么短语来找到此部分？”。