# README 文档应该怎么写？这些工具或许可以帮到你

> 本文开放前 70% 正文，剩余内容会员可见。

原文：https://utgd.net/article/20871

有的时候看到一些国内开发者的 Github 好项目，但是它们的 README 文档却写的过于简短，有时候连如何使用都需要自己摸索，或者借助网络上的资料才能知道更细节的内容。

README 文档往往是一个项目给人的第一印象，它不仅应该展示项目的基本信息，还应当为用户提供清晰的使用指导。海外的高星项目在这方面通常做的比较好。

README 文档并没有固定的模板，但一般来说，以下几部分是不可或缺的：

- 项目简介：一句话或几句话解释这个项目是做什么的。

- 安装步骤：详细说明如何安装、配置项目，包括所需的依赖和环境。

- 使用示例：提供一些简单的例子或操作步骤，让用户快速理解项目的用法。

- 贡献指南：如果你希望其他开发者为项目做出贡献，那么提供一些指导会非常有帮助。

- 许可证：注明项目的版权和许可信息。

这些内容可以帮助用户快速理解和使用你的项目，减少他们的学习曲线，也能让他们更有信心去使用或推广这个项目。

但如果你不确定如何写好这些部分，有些工具或许可以帮你省下不少时间和精力。

如果你觉得从头编写 README 文档有些困难，可以试试一些在线生成工具。比如 readme\.so 这个网站，它的界面非常直观，你只需要选择需要的模块，填入相应的内容，马上就能生成一个漂亮的 README 文档。

🔗 README\.so

编辑器里的每个模块都提供了一些示例内容，比如小徽章的引用方法、API 的 Markdown 表格、代码示例等等。简单组合一下都能看上去像模像样的。

这对于那些不太熟悉 Markdown 语法（真的，不是所有开发者都了解 Markdown）或者不清楚 README 应该包含哪些内容的开发者来说，能够大大降低编写门槛。

完成了基础的编写后，你还可以试试往 README 中添加更多有意思的小组件。可以增色不少。它们往往是通过添加一段 HTML，由外部的服务获取数据、生成图片来实现的。

比如最常见的双色小徽章就是来自 Badges Shield 项目。这些小徽章能够以各种各样的维度描述这个项目，比如采用的语言、版本号、协议、测试覆盖率等等。

🏠 Shields\.io 官网

🔗 badges/sh

---

[前往标准阅读页](https://utgd.net/article/20871?audience=web)