diff --git "a/\347\254\2544\351\203\250\345\210\206\342\200\224\342\200\224\345\220\257\345\212\250\350\207\252\345\267\261\347\232\204\345\274\200\346\272\220\351\241\271\347\233\256/\345\246\202\344\275\225\347\274\226\345\206\231 Readme" "b/\347\254\2544\351\203\250\345\210\206\342\200\224\342\200\224\345\220\257\345\212\250\350\207\252\345\267\261\347\232\204\345\274\200\346\272\220\351\241\271\347\233\256/\345\246\202\344\275\225\347\274\226\345\206\231 Readme" new file mode 100644 index 0000000000000000000000000000000000000000..d65521f7e6522a6afbb878852971b7a91bced21f --- /dev/null +++ "b/\347\254\2544\351\203\250\345\210\206\342\200\224\342\200\224\345\220\257\345\212\250\350\207\252\345\267\261\347\232\204\345\274\200\346\272\220\351\241\271\347\233\256/\345\246\202\344\275\225\347\274\226\345\206\231 Readme" @@ -0,0 +1,164 @@ +# 如何编写 Readme + +本文将介绍关于 readme 文档的编写. 主要从 readme 应该包含的几方面展开 + + + + + +## 项目名称 + +- 首先是项目名称, 给项目取一个名字在正常不过了. 一般我们会在 readme 的最开始用 `

项目名称

` 这样的方式来展示项目名称. 项目名称是在整个 readme 中最大的一个标题. + + + + + + + +## 项目介绍 + +- 项目介绍一般会跟着项目名称下面, 着重介绍项目解决的问题、项目提供的功能等. + + + +## 徽章 + +- 在 readme 中可以通过一些徽章来给其填上一点颜色 +- 这些会在一般在 项目名称下面 +- 徽章制作网站: http://shields.io/ + + + + + +## 使用 + +- 使用部分区分于项目名称和项目介绍, 它是一段新的标题. 采用比项目名称小一号的标题`

使用

` + +- 使用这里会有一些差异化, 有一些喜欢使用 `Usage` 作为标题, 也有选择用 `Example` 作为标题. 笔者看来这两者都可以, 它们都会将项目的使用告诉项目的使用者. 不过光看 readme 中的使用是不够的, 项目作者还需要提供更多的使用案例, 可以是测试用例, 使用文档等, 这些内容通过 wiki 或者 markdown 等形式进行编写后在使用中提供一个跳转地址进行阅读 + + + + + +## 安装 + +- 安装和使用一样都采用比项目名称小一号的标题`

安装

` + +- 安装的英文比较统一 `Install` + +- 在安装中会根据不同语言来编写具体的安装方式,下面举几个例子 + + 如 npm 管理的情况下可以直接用 `npm install package_name` + + maven 管理的情况下可以直接贴出 maven 坐标地址 + + + + + +## 获取帮助 + +- 获取帮助部分会写下当使用者遇到问题后如何向项目负责人、负责团队寻求帮助. + +- 获取帮助的英文: + + + + + +## 从源码构建 + +- 从源码构建部分会介绍当获取到当前项目的源代码后如何将其编译的过程. +- 从源码构建的英文: `Building from Source` + + + + + + + +## 报告问题 + +- 报告问题部分会介绍当使用者发现问题了后应该如何将问题告诉项目负责人、项目负责团队 +- 报告问题的英文: `Reporting Issues` + + + + + +## 行为准则 + +- 行为准则一般会是一个文件, 会专门编写, 在 readme 中使用跳转的形式进行阅读 +- 行为准则的英文: `Code of Conduct` + + + +## 文献资料 + +- 文献资料一般是大量文件, 这些文件都是对当前项目的文档补充. +- 文献资料的英文: `Documentation` + + + +## 贡献 + +- 贡献中会写出贡献代码或者其他内容的方式, 一般也会有一个单独的文件进行详细说明. +- 贡献的英文: `Contributing` + + + + + +## 功能列表 + +- 功能列表部分会列出当前项目中的部分也可能是所有的功能 +- 功能列表的英文: `Features` + + + + + +## 变更日志 + +- 变更过日志是一个文件, 在其中会有整个项目的变更记录. +- 变更日志的英文: `Changelog` + + + +## 作者 + +- 作者部分会将参与本项目的人都会在这里编写 +- 作者的英文: `Contributors` + + + + + +## 许可证 + +- 许可证部分会贴出当前项目所使用的许可证, 以及许可证连接地址 + +- 许可证的英文: `License` + + + + + + + + + +- 在了解了 readme 中有那些内容后就可以着手编辑了. 各位可以使用文中提到的英文作为标题,也可以使用中文, 如果需要国际化可以采用 `readne_语言标记.md`的形式来作为文件名称, 为了突出 readme 可以将这些 `readme_` 文件都大写标 `README_` + + + + + + + + + + +