python开发软件的实例-如何编写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) 使用模板

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

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

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

python开发软件的实例-如何编写Python软件开发文档（7个技巧）相关推荐

编写一个项目开发文档
项目开发过程中为了增加程序的可读性和程序的健壮性, 方便后期程序的调试和维护,所以需要在开发过程中统一技术规范,一般会在项目初期确定好相关文档作为这一统一的规范.不同公司会对文档做不同要求,划不同的分 ...
软件开发文档的价值和作用
现代软件研发理念强调敏捷开发,快速迭代,高效地响应用户的需求变化.可以说,自从有了敏捷方法,有相当一部分程序员长出一口气:终于可以不用写文档了. 那么,事实真的如此吗,文档应不应该写,应该如何编写? ...
软件开发文档整理（之）一张示意图 | 清晰明了
在整个软件开发周期,开发文档是必不可少的资料,它们贯穿于整个开发周期,用来评估计划.规划进度.项目管理.软件测试.软件发布,可以说至关重要. 开发文档必须归档,没有归档的文档作用大打折扣,时效 ...
python软件开发-如何编写Python软件开发文档（7个技巧）
开发文档是经常被程序员忽略的工作,有时也会被管理者忽略.这往往是由于在项目生命周期结束的后期缺乏时间,以及人们认为自己不擅长写作,其中一些人确实写不好,但他们中的大多数能够完成一个良好的文档. 在任何 ...
python写软件实例-如何编写Python软件开发文档（7个技巧）
开发文档是经常被程序员忽略的工作,有时也会被管理者忽略.这往往是由于在项目生命周期结束的后期缺乏时间,以及人们认为自己不擅长写作,其中一些人确实写不好,但他们中的大多数能够完成一个良好的文档. 在任何 ...
python开发工程师面试题-2019超实用Python开发工程师面试题分享
原标题:2019超实用Python开发工程师面试题分享 Python诞生很早,但真正火爆时间并不长.目前Python语言的应用领域非常广泛,主要有系统编程.图形处理.数学处理.文本处理.数据库编程.网 ...
python开发工程师面试题-分析经典Python开发工程师面试题
你知道吗?实际上Python早在20世纪90年代初就已经诞生,可是火爆时间却并不长,就小编本人来说,也是前几年才了解到它.据统计,目前Python开发人员的薪资待遇为10K以上,这样的诱惑很难让人拒绝 ...
python开发工程师是干嘛的-python工程师是做什么的
对于大多数人来说,可能只知道python这个名字,或者也听说过Python在云计算.大数据.人工智能里面都有运用,学Python未来发展前景还比较好.但是并不知道Python具体可以做些什么,在哪些应 ...
Python开发就业岗位有哪些？Python薪资待遇如何？
Python开发就业岗位有哪些?Python就业岗位分为:Python后端.数据分析.数据挖掘.机器学习.爬虫等.后端岗位多,Python岗位占50%是爬虫工程师的10倍:其次是数据分析岗位,仅次于P ...

python开发软件的实例-如何编写Python软件开发文档（7个技巧）

python开发软件的实例-如何编写Python软件开发文档（7个技巧）相关推荐

最新文章

热门文章