如何编写Python软件开发文档(7个技巧)

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

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

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

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

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

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

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

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

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

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

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

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

2) 准确定位读者

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

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

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

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

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

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

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

4) 撰写贴合内容的标题

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

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

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

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

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

举个例子,假设我们想要展示如何使用 parse() 函数:
from atomisator.parser import parse
#用法如下:
stuff = parse("some-feed.xml")
stuff.next()
输出结果为:

{'title':'foo','content':'blable'}

更好的例子应该是,让解析器知道如何使用解析函数返回一个 feed 的内容,可作为一个顶级函数使用,如下所示:
from atomisator.parser import parse
#用法如下:
my_feed = parse("http://tarekziade.wordpress.com/feed")
my_feed.next()
输出结果为:

{'title':'eight tips to start with python','content':'The first tip is ..., ...'}

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

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

6) 文档内容以实用为主

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

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

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

7) 使用模板

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

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

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

编程帮,一个分享编程知识的公众号。跟着站长一起学习,每天都有进步。

通俗易懂,深入浅出,一篇文章只讲一个知识点。

文章不深奥,不需要钻研,在公交、在地铁、在厕所都可以阅读,随时随地涨姿势。

文章不涉及代码,不烧脑细胞,人人都可以学习。

当你决定关注「编程帮」,你已然超越了90%的程序员!

编程帮二维码
微信扫描二维码关注