如何写好 README (开发文档书写规范)
2016-10-13 09:05
309 查看
推荐文章:
链接:https://zhuanlan.zhihu.com/p/22900142
来源:知乎
著作权归作者所有。商业转载请联系作者获得授权,非商业转载请注明出处。
简评:因为 README,6 个月后的你仍然知道当初写了什么;因为 README,其他人看一眼就能知道是否需要;因为 README,让你的代码更有质量;因为 README,你成了个作家。
README 是一种说明文件,通常随着一个软件而发布,里面记载有软件的描述或注意事项。这种档案通常是一个纯文字文件,被命名README.TXT、README.1ST或http://READ.ME等等;但也有RTF或DOC格式的读我档案。它的档名通常是以大写英文来命名的,因为大写英文字母比小写有着较小的ASCII码;亦因此在一些以ASCII排序档案的环境里,它能被保证被列在档案列表的第一位。这种档案的特殊命名使任何人能第一时间发现并阅读这个档案,即使他们本身并没有关于
README 的相关知识。
README 应该要简短,并且能够节省时间。
完整的 README 应该包括以下:
项目和所有子模块和库的名称(对于新用户,有时不同命名会导致混乱)
对所有项目,和所有子模块和库的描述
如何使用 5-line code(如果是一个库)
版权和许可信息(或阅读许可证)
抓取文档指令
安装、配置和运行程序的指导
抓取最新代码和构建它们的说明(或快速概述和「阅读 Install」)
作者列表或「Read AUTHORS」
提交bug,功能要求,提交补丁,加入邮件列表,得到通知,或加入用户或开发开发区群的介绍
其他联系信息(电子邮件地址,网站,公司名称,地址等)
一个简短的历史记录(更改,替换或者其他)
法律声明
Apache HTTP Server 的
README 和 GNU 的README 都很简洁清晰。
对于格式,我个人尽可能的坚持 UNIX 的传统,而且在 github 上用 Markdown 格式。
举个例子:
如果用英文写的文档,只用 ASCII
如果可能写不同语言,比如README.ja
每行少于 80 个字符
段落之间空行
标题下划线
使用空格而不是 tab 锁紧(对此园长怀疑作者是空格神教的)
把以上结合起来就成了:
最后贴上wiki对README的定义:
A readme (or read me) file contains information about other files in a directory or archive and is very commonly distributed with computer software.
and it lists the following contents:
configuration instructions
installation instructions
operating instructions
a file manifest
copyright and licensing information
contact information for the distributor or programmer
known bugs
troubleshooting
credits and acknowledgements
a changelog
本文翻译自:How to write a good README(stackoverflow)
Art of README
作者:园长链接:https://zhuanlan.zhihu.com/p/22900142
来源:知乎
著作权归作者所有。商业转载请联系作者获得授权,非商业转载请注明出处。
简评:因为 README,6 个月后的你仍然知道当初写了什么;因为 README,其他人看一眼就能知道是否需要;因为 README,让你的代码更有质量;因为 README,你成了个作家。
README 是一种说明文件,通常随着一个软件而发布,里面记载有软件的描述或注意事项。这种档案通常是一个纯文字文件,被命名README.TXT、README.1ST或http://READ.ME等等;但也有RTF或DOC格式的读我档案。它的档名通常是以大写英文来命名的,因为大写英文字母比小写有着较小的ASCII码;亦因此在一些以ASCII排序档案的环境里,它能被保证被列在档案列表的第一位。这种档案的特殊命名使任何人能第一时间发现并阅读这个档案,即使他们本身并没有关于
README 的相关知识。
README 应该要简短,并且能够节省时间。
完整的 README 应该包括以下:
项目和所有子模块和库的名称(对于新用户,有时不同命名会导致混乱)
对所有项目,和所有子模块和库的描述
如何使用 5-line code(如果是一个库)
版权和许可信息(或阅读许可证)
抓取文档指令
安装、配置和运行程序的指导
抓取最新代码和构建它们的说明(或快速概述和「阅读 Install」)
作者列表或「Read AUTHORS」
提交bug,功能要求,提交补丁,加入邮件列表,得到通知,或加入用户或开发开发区群的介绍
其他联系信息(电子邮件地址,网站,公司名称,地址等)
一个简短的历史记录(更改,替换或者其他)
法律声明
Apache HTTP Server 的
README 和 GNU 的README 都很简洁清晰。
对于格式,我个人尽可能的坚持 UNIX 的传统,而且在 github 上用 Markdown 格式。
举个例子:
如果用英文写的文档,只用 ASCII
如果可能写不同语言,比如README.ja
每行少于 80 个字符
段落之间空行
标题下划线
使用空格而不是 tab 锁紧(对此园长怀疑作者是空格神教的)
把以上结合起来就成了:
Documentation ------------- GNU make is fully documented in the GNU Make manual, which is contained in this distribution as the file make.texinfo. You can also find on-line and preformatted (PostScript and DVI) versions at the FSF's web site. There is information there about ordering hardcopy documentation. http://www.gnu.org/ http://www.gnu.org/doc/doc.html http://www.gnu.org/manual/manual.html
最后贴上wiki对README的定义:
A readme (or read me) file contains information about other files in a directory or archive and is very commonly distributed with computer software.
and it lists the following contents:
configuration instructions
installation instructions
operating instructions
a file manifest
copyright and licensing information
contact information for the distributor or programmer
known bugs
troubleshooting
credits and acknowledgements
a changelog
本文翻译自:How to write a good README(stackoverflow)
相关文章推荐
- 如何使用javadoc规范java开发文档
- 如何写好软件开发需求文档
- web前端开发技术文档书写规范
- WEB前端开发规范文档以及如何提高代码编写效率
- 如何为开发项目编写规范的README文件(足球竞猜源码下载),此文详解
- 如何为开发项目编写规范的README文件(windows),此文详解
- 如何使用javadoc规范java开发文档
- 如何为开发项目编写规范的README文件(windows)
- Web程序开发中的规范和文档
- [转]使用javadoc规范java开发文档
- 计算机专业软件开发文档书写技巧和计算机学生毕业论文写作资料
- 文档知多少---走出软件作坊:三五个人十来条枪 如何成为开发正规军(二十五)[转]
- 读后感:文档知多少---走出软件作坊:三五个人十来条枪 如何成为开发正规军(二十五)
- web开发中怎么样使css书写规范?
- 项目开发流程规范文档
- 数据库开发文档编写规范
- 文档知多少---走出软件作坊:三五个人十来条枪 如何成为开发正规军(二十五)
- 归档文档模板(软件开发文档规范)
- 文档知多少---走出软件作坊:三五个人十来条枪 如何成为开发正规军(二十五) 推荐