如何编写开源项目的 README 文档

IT技术 • coding • 发表于 8 年前 • 最后回复来自 EvfamleJsy • 8 年前

运营一个开源项目就像在运营着一家 Startup，你期待更多人来使用你的项目，并给你的项目加 Star/提交 PR，但好的项目除了其自身真正契合了开发者的需求外，还需要一个好的 README。

有好的 README 文档的项目不一定是一个好开源项目，但一个好开源项目一定有一个好的 README。

目前 README 文档编写并没有规范，但一个友好的 README 是有其特征的，我们来看看一个好的 README 的必备要素。

国际化问题

首先要注意的是国际化问题，如果你希望自己的项目能获得更多人的使用，提供中英两种 README 文档是非常赞的。你可以在项目头部注明它。如 Coding 的 WebIDE 项目：

项目名及简介

好的项目名及简介是好项目必不可少的。开源项目名不宜过长（除非你有特别的理由这么做），如果你不知道如何给自己的项目起名，可以使用随机项目名产生器（适用于 Javascript 项目）；项目简介可以是简单的几句话，但项目简介要说明几个你的开源项目用户想迫切了解的问题，这包括：

这个开源项目是做什么的？
这个项目是什么语言编写的？
项目维护、CI、依赖更新状态（如果有的话，这也可以用）
项目可用版本及其他版本
Demo 或官网地址（如果有）

如 Coding 的 WebIDE 项目：

此外你还可以给项目增加一些图标以提高可读性，推荐使用 Shields.io

项目 Logo 和使用截图

你还可以将项目 Logo（如果有的话）放置在 REAME 顶部（这里推荐一个在线制作 Logo 的网站 Canva ），项目截图（Gif 动图更佳）也可以帮助你的用户更快速更直观地了解你的开源项目。

功能

你可以注明这个项目的功能特点，亮点特色会大大提高访客使用这个项目的概率。

如 Coding 的 WebIDE 项目。

用法

这是 README 中最重要的部分，你需要说明这个项目如何使用，这包括：

如何下载这个项目：一般情况下 git clone 该项目地址即可，当然你也可以提供其他包管理下载安装方式；
项目依赖：你需要说明编译运行这个项目前需要哪些依赖；
安装：你需要说明如何编译安装/运行这个项目；
部署：如果这个项目可以部署的话，请最好注明部署要注意的事项；
Debug 方法：理想状况下，你的用户会顺利编译并运行这个项目，但你要确保用户遇到了问题不会来打扰你（如提交 Issues），你还需要提供用户可能会遇到的常见问题；

贡献

对于一个开源项目来说，令其作者最开心的莫过于有人提交 Pull Request 了。加入一个 CONTRIBUTING 文档将大大提高他人贡献你的项目的概率。

你可以说明你的代码规范，项目架构，如何测试和提交 Pull Request 的正确格式，以及其他有利于开发者进行贡献的信息，这将会使你的项目变得更加的规整如一。你可以在项目根目录新建一个 CONTRIBUTING 进行详细的说明并在 README 中添加其文件锚链接。如 Google 的 Template：

版权

版权是非常重要的，如果没有声明版权，很多用户特别是企业级用户将受制于法律问题，无法使用你的项目。关于如何选择开源项目许可证，推荐阅读这篇文章：《如何选择开源许可证？》

如 Coding 开源的帮助文档版权：

鸣谢

你还可以感谢直接或间接为这个项目做出贡献的人、项目。

如 ttyd 项目：

其他

我们推荐使用 Markdown 编写你的 README，请最好注意排版问题以增加文档可读性，推荐阅读 Coding 的《文案排版规范》。

这就是一个好的 README 所需元素了，当然你还可以增加其他任何利于开发者的信息如 Roadmap 等等，这因项目而异。现在，去完善你的开源项目信息或开始做一个开源项目吧！

一些建议：选择一个好的代码托管平台/社区可以让你的开源项目获得更多曝光，你可以在 Coding 的冒泡社区（可以理解为程序员的朋友圈）发布你的项目简介，截图和地址，与 30 万中国开发者分享你的开源项目；另外我们推荐同时 push 项目到 Coding 和 GitHub（可参考该回答），得益于 Coding 遍布全国的 CDN，国内用户 clone 你的项目时的速度将大大提升。

Happy Coding ; )

（完）

你可能会感兴趣的文章：