python开发技术文档范文_程序员编写技术文档的新手指南

这是一篇帮助你给第一个项目写文档的指南。

万事开头难,我希望这份指南能把你引导到正确的道路上。

最后,你应该有一个可以公开发布的项目。

请轻松地阅读完这篇文章,或者简单地把它当作参考。

为什么要写文档?

你将会在 6 个月后使用你的代码

我发现一开始从利己的角度来解释这个问题会比较有吸引力。写文档最好的理由就是你将会在 6 个月后使用你的代码。你 6 个月前写的代码跟别人写的代码对你来说通常没有什么区别。你将会带着一种熟悉的感觉读你的代码。然后一种不良的预兆悄悄逼近,你发现写代码的人毫无经验,毫无智慧。

当你读完几个月前很简单易懂或者取巧的代码之后,你就会开始同情你的用户。只要我写下为什么我要这么做,生活就会变得如此简单。文档能让你记录代码为什么这样写的原因。同样地,代码注释解释了为什么,而不是怎么做,文档也是这样。

你想要别人使用你的代码

你已经写了一段代码,并且发布了它。你这样做是因为你认为别人可能觉得它有用。但是,人们需要先知道为什么你的代码对他们可能有用,才会决定使用它。文档可以告诉人们这个项目对他们有用。

如果人们不知道你项目存在的意义,他们不会使用它。

如果人们不知道怎么安装你的程序,他们不会使用它。

如果人们不知道怎么使用你的代码,他们不会使用它。

只有少数人会深入研究你的代码并且使用它。几乎没人会使用你的代码,除非它有好的文档。如果你真的热爱你的项目,给它写文档,让其他人使用它。

你需要别人的帮助

开源项目是具有魔力的,对吗?你发布了代码,然后 code gnomes 出现并且让你的代码更好。

当你发布代码的时候会有一种奇妙的感觉产生。它通过各种方式出现,但总是能让你兴奋不已。有人在使用我的代码?这是一种混合了恐惧和兴奋的感觉。

我创造了价值!

如果它出错了怎么办?!

我是一个开源项目开发者了!

天哪,别人在使用我的代码。。。

写好的文档能够减轻这种恐惧。很多恐惧来自于给世界创造东西。我最喜欢的关于这个问题的引文如下所示:

恐惧来自于你做着重要的事情。

如果你在做不让你恐惧的事情,那么它对你或者世界都没有益处。

恭喜你感到恐惧!它意味着你在做重要的事情。

实际上,不完全是这样。

开源项目确实令人感到惊奇,但它同样必须符合现实世界的规则。你必须有付出,才有收获。

在你为项目付出大量工作之后,才能获得贡献。

在你的项目有用户之后,才能获得贡献。

在你的项目有文档之后,才能获得贡献。

文档也为你项目的第一次贡献提供平台。很多人从来没有为开源项目贡献过,让他们修改代码比修改文档可怕得多。如果你没有文档,你将失去这类文档贡献者。

文档让你的代码更好

有一个古老的事实:把东西写下来帮助你更好地思考。头脑里产生一个听起来不错的想法很容易,但是把想法写到纸上就需要思想上的升华。

写文档能提升代码的设计。在纸上讨论你的API和设计决定可以让你用一种更正式的方式思考它们。它还有一个不错的副作用:让别人按照你原来的意图贡献代码。

你想成为一个更好的写作者。

写文档跟大多数人体验过的写作方式不同。技术写作是一种非与生俱来的艺术。写文档将会是你成为更好的技术写作者这条路的起点,作为程序员,这是一个有用的技能。

写作会随着时间的流逝变得更容易。如果你好几个月没写东西,再次动笔就会变得更加困难。边做项目边写文档将会让你保持一个合理写作节奏。

用什么工具写作

简单的开始是取得实际成果的最好方式。我将会提供一条平坦的路给你走,在你有了基本的想法之后,你可以扩大范围。这些工具很强大并且容易使用。这将移除写作的障碍。

这篇文章中的例子在 Markdown 和 reStructuredText 中都是有效的。reStructuredText 有一点难用,但是更强大。我推荐你两个都看看,然后决定哪个你想要用。

纯文本版本控制

做为程序员我们生活中纯文本的世界里。我们的文档工具不应例外。我们想要能把纯文本转化成漂亮的 HTML 的工具。我们还有一些最好的跟踪文件变化的工具。为什么我们写文档的时候会放弃使用这些工具?这套工作流是强大的,并且对开发者来说很熟悉的。

基本例子

1

2

3

4

5

Resources

---------

*Online documentation:http://docs.writethedocs.org/

*Conference:http://conf.writethedocs.org/

上面的文字将渲染成标题,下面带着列表。URLs 将会被自动超链接。这写起来很容易,不但作为纯文本有意义,而且还能很好的渲染成 HTML。

README

你第一个应该写的文档是 README。如果你提供了合适的扩展名,代码托管服务会自动把你的 README 渲染成 HTML。它也是大多数用户跟你的项目的第一次互动。所以,一个可靠的 README 对你的项目十分有用。

文档写什么

现在我们来讨论重要的事情。确保你的用户能得到他们需要的所有信息,但不要太多。

首先,你需要问自己:文档是为谁而写。一开始,你只需要吸引两类的读者:

用户

开发者

用户是指那些只是想使用你的代码,而不管关心它怎么工作的人。开发者是指那些想要给你的代码做贡献的人。

你的项目解决了哪些问题

很多人会通过你的文档搞清楚你的项目是什么。有人会提到它,有人会随机地用 Google 搜索一个短语。你应该解释你的项目做了什么和它存在的意义。Fabric 这方面做的很好。

一个代码的小例子

提供一个生动的例子来告知用户你的项目通常会被用来做什么。 Requests 是一个很好的例子。

一个代码和问题追踪的链接

人们有时候喜欢浏览源代码。他们可能对归档他们发现的代码 BUG 感兴趣。尽可能地让那些想要为项目做贡献的人做这件事很容易。我认为 Python Guide 做得很好,因为它有指向代码部分的链接。

常见问题(FAQ)

很多人会有相同的问题。如果问题一直发生,你应该适当地修改你的文档或者代码来解决问题。但是总是有一些经常被问的关于项目的问题,不能改变的的事情等。把这些记录在文档中,并且使其保持最新。FAQs 通常会过时,但当它们被很好的维护时,它们就是黄金资源。 Tastypie 做得很好,它把 FAQs 整理成“Cookbook”。

如何获取支持

邮件列表?IRC 频道?文档要记录如何获取帮助和跟项目社区交流。 Django 这方面做得很好。

给贡献者的信息

在项目中,人们通常有怎么做事情的标准。你应该记录在文档上,以便于别人写代码时能符合项目的标准。Open Comparison 这方面做的很好。

安装说明

一旦人们决定使用你的代码,他们需要知道如何获取它和运行它。但愿你的安装指令只有几行用于基本使用。如果有必要,给出提供更多信息和说明的页面链接。我认为 Read the Docs 中我们做得很好。

你的项目许可证

BSD?MIT? GPL? 这些证书可能对你来说没什么,但是使用你代码的人会很关心这个。考虑一下你想要用什么证书发布你的项目,务必选择一个互联网上的标准许可证。

下一步做什么

在你遵循上面的指南之后,我们相信你的项目将会成功。进一步的参考资料,查看这篇文章 如何维护一个开源项目。

模板

给你一个 README 的模板。如果你使用 markdown 的语法,把它命名为 README.md。如果你使用 reStructuredText 的语法,把它命名为 README.rst。

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

$project

========

$project will solve your problem of where tostart with documentation,

by providingabasic explanation of how todoit easily.

Look how easy it istouse:

import project

# Get your stuff done

project.do_stuff()

Features

--------

-Be awesome

-Make things faster

Installation

------------

Install$project by running:

install project

Contribute

----------

-Issue Tracker:github.com/$project/$project/issues

-Source Code:github.com/$project/$project

Support

-------

Ifyou are having issues,please let us know.

We haveamailing list located at:project@google-groups.com

License

-------

The project islicensed under the BSD license.

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/566800.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

长沙计算机中级职称分数公布,大家所期待的2020年湖南省长沙中级职称评审公示...

原标题:大家所期待的2020年湖南省长沙中级职称评审公示年底了,各大考试差不多都快结束了。唯一就是湖南长沙的土建中级职称评审结果待公示,湖南岳阳,湘潭等地方也相继公示。2019年湖南省中级职称评审(长沙市)12月24号公示&#xf…

android平台上持久化存储3种手段_深入学习Redis :持久化

前言在上一篇文章中,介绍了Redis的内存模型,从这篇文章开始,将依次介绍Redis高可用相关的知识——持久化、复制(及读写分离)、哨兵、以及集群。本文将先说明上述几种技术分别解决了Redis高可用的什么问题;然后详细介绍Redis的持久…

印刷 计算机控制系统,陶瓷印刷计算机直接制版控制系统设计与实现

摘要:"陶瓷印刷计算机直接制版系统"是为陶瓷印刷制作印版的高度自动化系统,它将计算机引入制版过程中,简化印版制作工序,提高印版制作质量. 首先,本文介绍计算机直接制版系统的发展现状和趋势,并提出以此为基础,开发陶瓷印刷计算机直接制版系统的必要性和…

自动驾驶芯片_自动驾驶芯片“争夺战”

伴随着智能汽车时代的加速到来,自动驾驶芯片“争夺战”也越演越烈。继奥迪、宝马、长安、广汽、小鹏等汽车厂商“摩拳擦掌”L3级自动驾驶后,近日本田扔出了一个大消息,L3级自动驾驶汽车将于明年3月正式开售。至此,全球已经进入L3级…

通信技术计算机通信方向专业,江西科技学院2014年招生通信工程(计算机通信方向)专业介绍...

专业代码:080703一、专业培养目标本专业培养掌握通信工程的基本理论和基本知识,获得计算机通信工程实践的基本训练,具备从事现代电子通信系统和通信网络的生产、设计、调试和应用能力的高级应用型工程技术人才。二、专业就业方向学生毕业后可…

r语言将百分数化为小数_「淮南师出」教师资格/招聘小学数学:《百分数与小数的互化》...

教学目标:1、利用已有知识迁移、类推、发现百分数和小数互化的规律和方法。2、理解、掌握百分数和小数互化的方法,并能熟练运用,进一步体会数学之间的内在联系,增强思维的深刻性。3、通过合作交流、探索发现等数学学习活动教给学生…

wps表格里面计算机在哪里,WPS的Word居然还有计算神器?在哪里能找到又是怎么进行计算呢?...

说到计算器,恐怕好多小伙伴第一时间会想到WPS的Excel和微软的Excel表格,其实,WPS的Word也有计算器,只是隐藏了起来好多人不知道而已。只要找到它,我们在Word里也能进行加减乘除的计算了,下面白豆芽就给大家…

git reset 怎么还原_如何在Git中重置、恢复,返回到以前的状态

编辑推荐:本文来自51cto,在本文中,我们将带你了解如何去重置、恢复和完全回到以前的状态,做到这些只需要几个简单而优雅的Git 命令。用简洁而优雅的 Git 命令撤销仓库中的改变。使用 Git 工作时其中一个鲜为人知(和没有意识到)的方面就是&…

u盘复制到计算机的文档打不开怎么办,从电脑复制到U盘的文件打不开该怎么处理...

首先我们来看看,怎样的操作会让复制到U盘的文件无法打开?一种操作是,打开电脑文件夹,在文件上点右键,选“发送到-桌面快捷方式”。这样,在电脑桌面上就出现了一个文件的快捷方式。2、桌面上新建立的快捷方式…

深入浅出:Go 语言中值传递与引用传递的原理解析

深入浅出:Go 语言中值传递与引用传递的原理解析 引言Go 语言中的值传递什么是值传递?Go 语言中值传递的工作原理代码示例 Go 语言中的引用传递什么是引用传递?Go 语言中引用传递的工作原理代码示例 值传递与引用传递的比较优势和劣势应用场景…

arcgis显示后台错误_死亡、税收和Esri ArcGIS 999999错误:如何修复

死亡、税收和Esri ArcGIS 999999错误:如何修复如何修复Esri 999999错误生活中有些事情是确定的。在Arcgis,是 Esri 999999 error。基本上,当Arcgis不能指定导致错误的原因时,它会发出这个一般性错误。也就是那个让你们都泪流满面的…

专科学数控还是计算机,盘点适合专科男生学的专业 哪些专业好就业

正所谓:男怕入错行,女怕嫁错郎。对于专科男生来说,哪些专业好就业呢?下面和小编一起来看看吧!1、数控加工专业随着数控制造增多,我国对于数控加工专业人才严重缺乏。选择学数控加工专业的专科男生在毕业后&…

finditerable 转list_Iterable/Iterator 转 list

先简单介绍一下iterable和iterator:iterator为Java中的迭代器对象,是能够对List这样的集合进行迭代遍历的底层依赖。而iterable接口里定义了返回iterator的方法,相当于对iterator的封装,同时实现了iterable接口的类可以支持for ea…

牛顿莱布尼茨计算机公式,牛顿莱布尼茨公式

《牛顿莱布尼茨公式》由会员分享,可在线阅读,更多相关《牛顿莱布尼茨公式(17页珍藏版)》请在人人文库网上搜索。1、装订线教学过程1、复习旧知识,引入课题(1)复习:定积分的概念及几何意义原函数的概念导数的定义(2)课题引入&#…

ap设置 维盟660g_New丨维盟双频百兆11ac入墙AP:WAP-3018穿墙效果不一样!

新的9月,维盟新品bulingbuling闪亮登场看这里 维盟WAP-3018WAP-3018是一款入墙式无线AP,64M内存,8M闪存,支持智能无线技术,2.4G和5G双频并发,无线传输速率1167Mbps,带功率放大器,穿墙…

研究生夏令营计算机题目,2017计算机学科夏令营上机考试-B编码字符串

EF里单个实体的增查改删以及主从表关联数据的各种增删 改查本文目录 EF对单个实体的增查改删 增加单个实体 查询单个实体 修改单个实体 删除单个实体 EF里主从表关联数据的各种增删改查 增加(增加从表数据.增加主从表数据) 查询(根据主表找从表数据.根据从表 ...简单而又复杂的…

hive 十六进制转十进制_hive 常用运算

第一部分&#xff1a;关系运算Hive支持的关系运算符•常见的关系运算符•等值比较: •不等值比较: <>•小于比较: <•小于等于比较: <•大于比较: >•大于等于比较: >•空值判断: IS NULL•非空判断: IS NOT NULL•LIKE比较: LIKE•JAVA的LIKE操作: RLIKE•R…

红米note2能刷机没显示无服务器,红米note2怎么刷机 红米note2刷机教程

大家应该知道吧!现在手机市场已经被智能手机垄断了&#xff0c;走到哪儿智能手机都跟我们形影不离。虽然像三星、 苹果 一样的大牌手机比较出名&#xff0c;但是我们的国产手机这几年发展的也是很不错的&#xff0c;就好比国内最火爆的 小米 手机&#xff0c;这个品牌的手机上市…

all any 或 此运算符后面必须跟_any和all组合运算符用法区别

Any、All与&gt、&lt、、组合和In的意义、用法的区别SELECT * FROM ORDERSWHERE EXISTS(SELECT *FORM ORDERSWHERE NAME#SB)这样会返回orders里面所有的值&#xff0c;而不是只有NAME#SB的值改成SELECT * FROM ORDERS O1WHERE EXISTS(SELECT *FORM ORDERS O2WHERE O1.NA…

css控制的代码,通过CSS控制把网页上的代码美化

博客发布文章时&#xff0c;如果文章里有代码块的&#xff0c;通过pre或者code可以让代码块更好美观&#xff1b;有效提升阅读感受。它就像是IDE工具里的主题一样&#xff0c;看着眼睛舒服&#xff1b;这个问题困扰了我很久&#xff0c;由于时间的问题&#xff0c;一直没解决。…