make-a-readme

# 制作 README > 来源: [makeareadme.com](https://www.makeareadme.com) 作者 Danny Guo > > “因为没人能（暂时）读懂你的心思” ## README 101 ### 它是什么？ README 是一个介绍和解释项目的文本文件。它包含理解项目内容通常所需的信息。 ### 为什么要制作它？ 这是一种简单的方法，可以回答受众关于如何安装和使用你的项目，以及如何与你协作的常见问题。 ### 谁应该制作它？ 任何从事编程项目的人，特别是如果你希望其他人使用或贡献代码时。 ### 什么时候制作它？ 绝对要在向其他人展示项目或将其公开之前。你可能希望养成将其作为新项目中创建的第一个文件的习惯。 ### 应该放在哪里？ 在项目的顶层目录中。这是项目新手开始的地方。GitHub、Bitbucket 和 GitLab 等代码托管服务也会寻找你的 README，并将其与项目中的文件和目录列表一起显示。 ### 应该如何制作？ 虽然 README 可以用任何文本文件格式编写，但目前最常用的是 Markdown。它允许你添加一些轻量级的格式。你可以在 [CommonMark 网站](https://commonmark.org/) 上了解更多信息。 ## 优秀 README 的建议 每个项目都是不同的，所以要考虑哪些章节适用于你的项目。还要记住，虽然 README 可能太长太详细，但**太长总比太短好**。如果你认为你的 README 太长，请考虑使用其他形式的文档，而不是删减信息。 ### 名称 为你的项目选择一个不言自明的名称。 ### 描述 让人们知道你的项目具体能做什么。提供背景信息，并为访问者可能不熟悉的任何参考资料添加链接。也可以在此处添加“功能”或“背景”小节。如果你的项目有替代品，这里是列出差异化因素的好地方。 ### 徽章 (Badges) 在一些 README 上，你可能会看到传达元数据的小图片，例如项目的所有测试是否通过。你可以使用 [Shields.io](http://shields.io/) 添加一些徽章。许多服务也有添加徽章的说明。 ### 可视化内容 根据你制作的内容，包含截图是一个好主意