如何编写合格的项目说明[ReadMe]文档?

昨天有一位同学在微博上问我关于GitHub 上为何Build 一个New Repository GitHub文件目录结构中为何总是存在Read ME.rb格式的文件? 如下:

其实如果当你打包或是开源协议授权方式分发你的Source Code.在构建完整项目结构的根目录下应该有一个名为ReadMe的文件来说明当前版本源码结构或版本信息.如果你常看开源项目也会发现一个规律.在你拿到一个源码解压后第一件事就是找对该Project的ReadMe文件阅读.

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最基本元素.