7个编写Python软件开发文档技巧

开发文档是经常被程序员忽略的工作，有时也会被管理者忽略。这往往是由于在项目生命周期结束的后期缺乏时间，以及人们认为自己不擅长写作，其中一些人确实写不好，但他们中的大多数能够完成一个良好的文档。

在任何情况下，匆忙编写文档的结果是文档会变得一团糟。大多时候，开发人员讨厌做这种工作，尤其当现有文档需要更新时，情况会更糟。因为经理不知道如何处理更新，许多项目只是提供简陋而又过时的文档。

编写良好的文档在许多方面比编写代码更容易，大多数开发人员认为这很难，但通过遵循一组简单的规则，它会变得非常容易。

本节给初学者介绍了 7 条应该遵循的规则，可以应用在所有情况下，让编写开发文档事半功倍。

1) 专注于想法，然后审查和塑造你的文本

要知道，几乎没有人在第一次就写出完美的开发文档，因为多数人在编写文档时都尝试一次性将文档编写到完美，为此他们每写两句就停止写作，然后阅读他们并做一些修正。这意味着，他们将重点都放在文本的内容和风格上。

这种编写方式的结果往往没有预期的那么好，原因很简单，人们在还没有想清楚要写的内容之前，就将大量的时间和精力花在修正文件的风格和形状上。

我认为，正确的编写方式应分为 2 步，第一步无需考虑文本的风格和组织，专注于编写文档的内容。注意，最好能够将所有的想法都写在纸上，至于怎么写先不考虑。

也就是说，第一步的重点就是打造内容，只要不是关于内容的问题（例如语法错误等），都不需要关心。

通过这种方式，开发者能够专注于他的想法，并且可能会从想到更多的内容，而不只局限于其最初的想法。注意，在编写过程中，很容易在头脑中一闪而过一些想法，当它们出现时，比较好的的做法是将它们写到纸上，写完后可以继续回到当前的写作中。

第二步就是回读整个文本并对其进行修正，以便每个人都能理解。修正文本意味着要增强其风格，纠正其错误，重新组织它，并删除任何冗余的内容。

总之，当编写开发文档的时间有限时，比较好的做法就是将可利用的时间一分两半，一半用于写作，一半用于清理和组织文本。

2) 准确定位读者

编写开发文档时，首先应该考虑清楚，谁会读这个文档？

千万不要认为定位读者很简单，因为开发文档解释了一个软件如何工作，并且通常为每个可能获取和使用代码的人而写，读者可能是正在寻找问题的合适技术解决方案的研究员，也可能是需要利用其实现特性的开发者，甚至架构师，也可以从架构的角度来看它是否符合需求。

因此，好的开发文档应该遵循一个简单的规划，即每个文本应该只针对一种类型的读者。而这也使编写文档更容易，因为我们可以准确地知道面对的是什么样的读者。

另外，开发文档中最好提供一个简短的介绍性文本，用来解释文档是什么，并知道读者去读他感兴趣的部分。

3) 读者更喜欢简短的句子

对于绝大多数读者来说，往往更喜欢短而简单的句子，而不是长篇大论的段落。

使句子短而简单的方法有如下几个：

• 每个句子不应超过 2 行；
• 每一段应只表达一个主要思想，最多包含 3 到 4 个句子；
• 每个想法的解释不要重复太多，避免像新闻那样一再重复，只要保证读者能够理解即可。
• 如果你不是一个真正优秀的作家，避免在文档中讲笑话，因为在技术文档中添加滑稽的语言是很难的，很少有人掌握它。如果你想添加一些幽默，可以将它们放到代码示例中。

4) 撰写贴合内容的标题

不好的软件开发文档几乎都存在一个问题，即我们知道文档中包含自己要找的信息，但却要花很长时间去找。当作者没有将它们的文本内容合理地组织到标题中时，就会出现这种情况。

因此，建议大家在编写开发文档时，将段落聚集在给定章节的有意义的标题下；整个文档的标题可以用短语来组织；文档的目录可以由所有章节的标题组成。

总之，撰写标题最简单的做法就是问自己：“在百度中输入什么短语才能找到此部分内容”？

5) 文档中应使用项目中的代码作为示例

当读者试图通过一个使用示例来理解一段代码如何运行时，不切实际的示例代码往往更让人难以理解。

举个例子，假设我们想要展示如何使用 parse() 函数：

from atomisator.parser import parse
#用法如下：
stuff = parse("some-feed.xml")
stuff.next()

输出结果为：

更好的例子应该是，让解析器知道如何使用解析函数返回一个 feed 的内容，可作为一个顶级函数使用，如下所示：

from atomisator.parser import parse
#用法如下：
my_feed = parse("http://tarekziade.wordpress.com/feed")
my_feed.next()

输出结果为：

这个微小的差距可能有点过分夸张，但实际上它能够使文档更有用，读者可以将这些代码行复制到一个 shell 程序中，理解 parse 将使用一个 URL 作为参数，并且返回包含博客条目的一个枚举型变量。

总之，文档中使用的代码示例应该在实际的程序中直接可用。

6) 文档内容以实用为主

其实，软件开发中所用的大部分方法，是不需要用文档进行说明的，相比更详尽的文档，使软件正常工作无疑更重要。因此，一个好的做法是只编写真正需要的文档，而不是编写一个详尽的文档集。

举个例子，对于管理员来说，只需在文档中说明软件是如何工作的就足够了，他们除了要知道这个工具的配置和运行方法之外，没有其他的需求。所以，这个文档应将范围限制"如何在自己的服务器上运行软件"。

可以运行的软件，远远胜过面面俱到的文档。

7) 使用模板

以维基百科为例，你会发现它每个页面的布局都是相似的，一侧有用于总结日期或事实的文本框，文档开头总有一个目录（包含该页面中的所有标题的链接），文档结尾处总有一个参考部分，等等。

使用维基百科的用户习惯了这个页面的布局，例如他们就可以快速查看每个页面的目录部分，还可以快速查看参考文献等等，固定的结构布局会提高用户的效率。

所以，使用模板强制文档安装固定的模式，可以使用户更高效地使用它们。