技术控

    今日:32| 主题:49249
收藏本版 (1)
最新软件应用技术尽在掌握

[其他] 如何写好 README

[复制链接]
幸福是个哑巴 发表于 2016-10-12 16:38:05
135 6

立即注册CoLaBug.com会员,免费获得投稿人的专业资料,享用更多功能,玩转个人品牌!

您需要 登录 才可以下载或查看,没有帐号?立即注册

x

如何写好 README-1 (英文字母,运行程序,许可证,第一时间,如何)

  简评:因为 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 锁紧(对此园长怀疑作者是空格神教的)  
  把以上结合起来就成了:
  [code]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[/code]  最后贴上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)
  欢迎关注
   知乎专栏「 极光日报 」,每日 3 篇优质英文文章。
   微信公众号「 极光开发者 」( jiguangdev ),每周 2 篇技术类文章
友荐云推荐




上一篇:Java正则表达中Greedy Reluctant Possessive 的区别
下一篇:Uncovering Secrets in the Offshore Leaks Database with Tom Sawyer Perspectives
酷辣虫提示酷辣虫禁止发表任何与中华人民共和国法律有抵触的内容!所有内容由用户发布,并不代表酷辣虫的观点,酷辣虫无法对用户发布内容真实性提供任何的保证,请自行验证并承担风险与后果。如您有版权、违规等问题,请通过"联系我们"或"违规举报"告知我们处理。

dbjsz888 发表于 2016-10-12 22:46:10
幸福是个哑巴英明!
回复 支持 反对

使用道具 举报

曼寒 发表于 2016-10-13 01:30:00
看起来好像不错的样子
回复 支持 反对

使用道具 举报

冯帅 发表于 2016-10-13 07:32:29
小鲜肉心塞
回复 支持 反对

使用道具 举报

景小燕 发表于 2016-11-14 15:14:35
成全别人,恶心自己!
回复 支持 反对

使用道具 举报

wazyyan1 发表于 2016-11-19 15:02:18
直播,握手!稍坐,楼主马上来!
回复 支持 反对

使用道具 举报

ncoo8567 发表于 2016-11-19 15:33:58
态度决定一切,不错!
回复 支持 反对

使用道具 举报

*滑动验证:
您需要登录后才可以回帖 登录 | 立即注册

本版积分规则

我要投稿

推荐阅读

扫码访问 @iTTTTT瑞翔 的微博
回页顶回复上一篇下一篇回列表手机版
手机版/CoLaBug.com ( 粤ICP备05003221号 | 文网文[2010]257号 )|网站地图 酷辣虫

© 2001-2016 Comsenz Inc. Design: Dean. DiscuzFans.

返回顶部 返回列表