项目中的README.md

Read Me文件的意义在于说明Source Code 做了什么? 运行在什么样环境下? 如何查看编辑代码? 其目的在于向使用者说明源码有一个概览情况的介绍. 至少要说明如下几个问题:

这份源码是用来做什么的?

如何去使用?

项目中重要的文件和子目录的结构信息?

那如何编写一个合格的ReadMe文档.一个合格的ReadMe文档应该包含哪些具体的信息?如下:

整个项目的介绍[说明创建项目意图或是解决问题等]

指出开发者编译整个项目需要的系统环境参数.并之处项目可能潜在的移植性问题.

当前项目中重要的文件和子目录的结构信息.[必须]

项目更多资源支持站点或是版本更新包获取所在的URL地址

编译或安装步骤说明.或是知名这些信息所在的文件名[类似GitHub则把版本情况放在Version单独文件中等做法 通常应该Install文件]

一般国外开源项目为了附属上源作者版权信息.会在该文档中注明项目主持人和参与者的名单列表.或是列出该信息所在文件[通常为Credits文件]

关于本项目的版本更新或当前项目进展现在等信息.或支持包含该信息的文件[通常为NEWS文件]

如上为关于一个关于ReadMe应该包含内容.其中也包含一定可选项.其实从GitHub做法来看.ReadMe内容非常有限.而是把这些内容信息分别规范在除了ReadMe之外其他一些独立的文件中. 类似关于项目的版本信息.Github做法放在一个独立的Version文件中.关于当前项目受权信息则是放在
LICENSE.txt
文件中.

如果采用这方式 这里有必要说明这些信息如何归类方式以及文件命名的规范问题.这里有一个很重要的原则.

越是常见的项目类型,越是应该按照约定俗成来构建项目的目录结构,尽量不要别出新裁.这些文件命名目的让在SourceCode容易别人识别阅读.这些文件名本身就在向读者传达许多信息。如果你遵照标准的命名规则就可以给那些探索者有价值得线索以便他们更好的理解你的意图. 而不是创造一些大家不熟悉命名.增加阅读障碍和难度.

那如何正确命名ReadMe之外项目说明文件?可以参考如下通用命名做法:

ReadMe或Read.Me 整个项目的结构信息说明.是分发是第一个需要阅读的文件.

Install:配置、编译或安装该项目的说明信息.一般是对项目运行环境参数配置说明.

Credits:本项目所有参与者或贡献者的姓名列表.

NEWS:本项目最近的一些新闻或进展的情况说明.

History:该项目的历史发展一些或是版本记录信息.

Copying:明确指出该项目使用许可证条款.通常采用
GNU
.

License:该项目许可证条款文件.

Manifest:项目结构所有的文件列表.

FAQ:以纯文本格式关于项目常见问题的解答.

TAGS:为Emacs或VI准备的标记文件.

从上述命名可以看出全部大写的文件时给他人阅读的文档.[其上全部都应该大写.]而不是项目的一个组成部分.

这里特别说明一下.在开始分发时.对于可能在软件编译或是运行 修改等过程中可能经常碰到问题.最好统一放入FAQ文件中.针对一些其他没有设计特殊问题.最好在FAQ文件指导用户如何采用什么渠道向你反馈或沟通该问题.

如果你维护过一定规模的用户群的项目.你一定会明白一个好的FAQ会减轻项目维护者几个数量级的负担.

另外在每次发布时都保留一个HISTORY文件和NEWS文件,并列明时间信息非常有好处。在所有其他文件中,这两个文件可以让你在遇到一些专利侵权法律问题时有所准备 [虽然这种情况至今还没有发生过,不过最好还是有备无患].

编写好的项目说明文档.养成好的操作习惯也是一种职业素养. 细节虽小.但俨然是这些小细节才组成一个优秀高效DEV最基本元素.

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 220,976评论 6 513
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 94,249评论 3 396
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 167,449评论 0 360
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 59,433评论 1 296
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 68,460评论 6 397
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 52,132评论 1 308
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 40,721评论 3 420
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 39,641评论 0 276
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 46,180评论 1 319
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 38,267评论 3 339
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 40,408评论 1 352
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 36,076评论 5 347
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 41,767评论 3 332
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 32,255评论 0 23
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 33,386评论 1 271
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 48,764评论 3 375
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 45,413评论 2 358

推荐阅读更多精彩内容

  • Android 自定义View的各种姿势1 Activity的显示之ViewRootImpl详解 Activity...
    passiontim阅读 172,253评论 25 707
  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
    卡卡罗2017阅读 134,687评论 18 139
  • linux资料总章2.1 1.0写的不好抱歉 但是2.0已经改了很多 但是错误还是无法避免 以后资料会慢慢更新 大...
    数据革命阅读 12,175评论 2 33
  • 所有正面管教鼓励咨询的信息是从初中同学王岚的朋友圈知道的,她的姐姐就是一位非常优秀的咨询师。 其实我并不是很关注朋...
    不zuo不die阅读 297评论 0 0
  • 其实我是根据这个电影想到了我妈妈。所以有点想家,我觉得在泡脚的时候总会有点惊喜出现的,比如看了很多值得看的电影,...
    sunshine何毛毛阅读 622评论 0 1