如何编写Python软件开发文档(7个技巧)
开发文档是经常被程序员忽略的工作,有时也会被管理者忽略。这往往是由于在项目生命周期结束的后期缺乏时间,以及人们认为自己不擅长写作,其中一些人确实写不好,但他们中的大多数能够完成一个良好的文档。
在任何情况下,匆忙编写文档的结果是文档会变得一团糟。大多时候,开发人员讨厌做这种工作,尤其当现有文档需要更新时,情况会更糟。因为经理不知道如何处理更新,许多项目只是提供简陋而又过时的文档。
编写良好的文档在许多方面比编写代码更容易,大多数开发人员认为这很难,但通过遵循一组简单的规则,它会变得非常容易。
本节给初学者介绍了 7 条应该遵循的规则,可以应用在所有情况下,让编写开发文档事半功倍。
这种编写方式的结果往往没有预期的那么好,原因很简单,人们在还没有想清楚要写的内容之前,就将大量的时间和精力花在修正文件的风格和形状上。
我认为,正确的编写方式应分为 2 步,第一步无需考虑文本的风格和组织,专注于编写文档的内容。注意,最好能够将所有的想法都写在纸上,至于怎么写先不考虑。
第二步就是回读整个文本并对其进行修正,以便每个人都能理解。修正文本意味着要增强其风格,纠正其错误,重新组织它,并删除任何冗余的内容。
总之,当编写开发文档的时间有限时,比较好的做法就是将可利用的时间一分两半,一半用于写作,一半用于清理和组织文本。
千万不要认为定位读者很简单,因为开发文档解释了一个软件如何工作,并且通常为每个可能获取和使用代码的人而写,读者可能是正在寻找问题的合适技术解决方案的研究员,也可能是需要利用其实现特性的开发者,甚至架构师,也可以从架构的角度来看它是否符合需求。
因此,好的开发文档应该遵循一个简单的规划,即每个文本应该只针对一种类型的读者。而这也使编写文档更容易,因为我们可以准确地知道面对的是什么样的读者。
另外,开发文档中最好提供一个简短的介绍性文本,用来解释文档是什么,并知道读者去读他感兴趣的部分。
使句子短而简单的方法有如下几个:
因此,建议大家在编写开发文档时,将段落聚集在给定章节的有意义的标题下;整个文档的标题可以用短语来组织;文档的目录可以由所有章节的标题组成。
总之,撰写标题最简单的做法就是问自己:“在百度中输入什么短语才能找到此部分内容”?
举个例子,假设我们想要展示如何使用 parse() 函数:
举个例子,对于管理员来说,只需在文档中说明软件是如何工作的就足够了,他们除了要知道这个工具的配置和运行方法之外,没有其他的需求。所以,这个文档应将范围限制"如何在自己的服务器上运行软件"。
使用维基百科的用户习惯了这个页面的布局,例如他们就可以快速查看每个页面的目录部分,还可以快速查看参考文献等等,固定的结构布局会提高用户的效率。
所以,使用模板强制文档安装固定的模式,可以使用户更高效地使用它们。
在任何情况下,匆忙编写文档的结果是文档会变得一团糟。大多时候,开发人员讨厌做这种工作,尤其当现有文档需要更新时,情况会更糟。因为经理不知道如何处理更新,许多项目只是提供简陋而又过时的文档。
编写良好的文档在许多方面比编写代码更容易,大多数开发人员认为这很难,但通过遵循一组简单的规则,它会变得非常容易。
本节给初学者介绍了 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) 使用模板
以维基百科为例,你会发现它每个页面的布局都是相似的,一侧有用于总结日期或事实的文本框,文档开头总有一个目录(包含该页面中的所有标题的链接),文档结尾处总有一个参考部分,等等。使用维基百科的用户习惯了这个页面的布局,例如他们就可以快速查看每个页面的目录部分,还可以快速查看参考文献等等,固定的结构布局会提高用户的效率。
所以,使用模板强制文档安装固定的模式,可以使用户更高效地使用它们。
所有教程
- socket
- Python基础教程
- C#教程
- MySQL函数
- MySQL
- C语言入门
- C语言专题
- C语言编译器
- C语言编程实例
- GCC编译器
- 数据结构
- C语言项目案例
- C++教程
- OpenCV
- Qt教程
- Unity 3D教程
- UE4
- STL
- Redis
- Android教程
- JavaScript
- PHP
- Mybatis
- Spring Cloud
- Maven
- vi命令
- Spring Boot
- Spring MVC
- Hibernate
- Linux
- Linux命令
- Shell脚本
- Java教程
- 设计模式
- Spring
- Servlet
- Struts2
- Java Swing
- JSP教程
- CSS教程
- TensorFlow
- 区块链
- Go语言教程
- Docker
- 编程笔记
- 资源下载
- 关于我们
- 汇编语言
- 大数据
- 云计算
- VIP视频