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个技巧）相关推荐
- 编写一个项目开发文档
项目开发过程中为了增加程序的可读性和程序的健壮性, 方便后期程序的调试和维护,所以需要在开发过程中统一技术规范,一般会在项目初期确定好相关文档作为这一统一的规范.不同公司会对文档做不同要求,划不同的分 ...
- android怎么集成sdk,集成方式-Android开发集成-SDK开发集成-信令-网易云信开发文档...
集成方式 网易云通信 SDK 支持两种方式集成. 1. 通过 Gradle 集成 SDK (推荐) 2. 通过类库配置集成 SDK 网易云通信 Android SDK 2.5.0 以上强烈推荐通过 G ...
- AutoCAD 开发文档，AutoLISP 教程，.Net AutoCAD开发教程，VB AutoCAD开发教程，ObjectARX 开发指南,VBA AutoCAD开发教程，ActiveX 开发指南
AutoCAD 开发文档, CAD开发者社区 - AutoCAD二次开发文档,CAD二次开发,CAD插件开发,中文CAD文档 - 中文CAD开发文档,CAD二次开发问题交流,优秀插件分享 AutoLI ...
- 共享单车APP开发文档
共享单车APP开发,共享单车APP开发文档.单车针对大家而言想来也不生疏,如同很多人会骑单车念书或是在周末出行的过程中会以单车做为出行的交通工具,所以说绝大多数人都是会骑单车:而在信息技术产业慢慢健全 ...
- python开发软件的实例-如何编写Python软件开发文档（7个技巧）
开发文档是经常被程序员忽略的工作,有时也会被管理者忽略.这往往是由于在项目生命周期结束的后期缺乏时间,以及人们认为自己不擅长写作,其中一些人确实写不好,但他们中的大多数能够完成一个良好的文档. 在任何 ...
- python写软件实例-如何编写Python软件开发文档（7个技巧）
开发文档是经常被程序员忽略的工作,有时也会被管理者忽略.这往往是由于在项目生命周期结束的后期缺乏时间,以及人们认为自己不擅长写作,其中一些人确实写不好,但他们中的大多数能够完成一个良好的文档. 在任何 ...
- python价格趋势软件_2020年，软件开发走势，Python势如破竹！
原标题:2020年,软件开发走势,Python势如破竹! 对于程序员而言,了解编程语言的发展趋势,有助于个人职业成长:而对于想要入行IT的新人而言,最大的疑惑大多来自于不知道该选择哪门编程语言发展前景 ...
- Python的IDE：基于Eclipse/MyEclipse软件的PyDev插件配置python的开发环境(不同python项目加载不同版本的python)—从而实现Python编程图文教程之详细攻略
Python的IDE:基于Eclipse/MyEclipse软件的PyDev插件配置python的开发环境(不同python项目加载不同版本的python)-从而实现Python编程图文教程之详细攻略 ...
- 浙江大学控制科学与工程学院冯冬芹教授团队招聘软件开发工程师（python）2名
岗位职责: 1.负责对典型工业控制系统通讯协议进行研究分析,解析出协议的一般性规律.协议号.功能码指令等: 2.利用python进行协议渗透测试系统开发,对上述协议做渗透测试研究,包括测试用例的设计与 ...
最新文章
- 综述 | Google-斯坦福发布深度学习统计力学
- oracle日期数据格式,oracle日期数据格式
- 浏览器差异总结，可以用此判断浏览器版本（转）
- WeStrom自定义设置修改快捷键
- 实验5.4 编程实现两字符串的连接（使用string类定义字符串对象）
- C#的变迁史 - C# 4.0 之多线程篇
- vue key重复_12道vue高频原理面试题，你能答出几道？
- excel不显示0_【扫盲】小白必看：excel表里数字格式常见的几种错误？
- Android串口示波器,解读一个超赞的开源串口虚拟示波器项目
- HeadFirst设计模式笔记——命令模式
- 2019年研究生数学建模竞赛优秀论文汇总
- QT语言版本支持---国际化语言家功能的使用
- vue项目接入高拍仪
- vscode通过扩展插件实现流程图绘制
- 程序员今年最值得关注的 23 种新移动技术
- PHP教程从入门到精通，PHP课堂笔记（一）网站构建
- 【电器识别】基于AlexNet网络实现电线杆、绝缘子、发电机和电容器等电器设备识别附matlab代码
- request属性 request.getAttribute()
- 在UE4中完美导入MMD的动作，表情；基本导入镜头，材质---最详细教程
- azure linux 修改内网ip,服务器修改内网IP地址