如何写好 README

GenAI LIVE! | 2025年6月4日

自述文件 (README) 是向人们展示您的项目可以做什么以及为什么它很重要的好方法，在这里我将向您展示如何编写好的自述文件。

TL;DR

查看我的社区健康repo，并按照其 README 中的说明快速开始。

准备好了吗？太棒了！开始吧😄

核心概念

你的 README 应该简洁地引导你访问所有其他资源。它应该尽快回答以下问题：

1. 该项目的目的是什么？（简短描述）
2. 我可以使用它吗？（先决条件）
3. 如果是，我该如何安装它？（安装、使用示例等）
4. 我能帮上什么忙？（许可、贡献等）

写作指南

摘自此处

以下是一些一般的写作指南：

1. 保持你的代码在原始文件状态下可读性。
   有时，人们可能会将你的项目视为未渲染的纯 Markdown 文件。这可能是为了编辑代码，也可能只是因为他们有你的代码本地副本。确保你的 README 文件对他们来说仍然可读。

   以下是一些有助于使您的 Markdown 即使是原始的也易于阅读的技巧：

- **Always break lines!** Set your editor to show a ruler at ~80 characters. This is done so that people who are reading this as a raw file don't have to scroll infinitely.

  This is not a hard and fast rule though. Also, you don't have to break a line for that one last word which overflows (except if it is "Pneumonoultramicroscopicsilicovolcanoconiosis" or something 🤣).

  ![WHOA WHOA WHOA - THAT IS A VERY LONG WORD](https://media.makeameme.org/created/whoa-whoa-whoa-5b8473.jpg)

- **Minimise HTML.** Keep your markdown file as much markdown-y as possible – you don't want people reading HTML! Only use HTML if it is really helpful to the readability of the rendered content. A good example of when to use an HTML tag is the `<details>` tag.

- **Use reference-style links** because you don't want a super long link to break the flow.

1. 保持轻松友好的语气。写作时要让读者感觉自己了解不多，但确实感兴趣。

2. 保持简短

3. 仅在需要补充信息时才链接到文件中的其他位置。
   链接时，请内联相关信息。

4. 尽可能多地使用图片、代码片段和命令。展示给他们看，而不是直接告诉他们。

5. 查看此 markdown 样式指南或此样式指南和其他可用的 markdown 样式指南。

编写 README

添加标题

显然，这应该首先出现在 README 中。考虑将其链接到项目的 GitHub 仓库。

包含徽章

徽章是展示细微信息的好方法。它们也能吸引眼球，但不要过度使用。

您还可以让这些徽章链接到相关页面。例如，星星徽章可以链接到观星者页面。

包含横幅图片/徽标

横幅图片更好，但你可以选择任意图片。看看这个由atom制作的精美横幅示例（巧合的是，我的大部分研究都是基于atom的代码库）。这个示例也很好地展示了如何放置logo。

您还可以在横幅下添加一些额外的图像。

描述

让你的项目描述简洁明了。你可以使用以下模板，借鉴了scottydocs 的 README 模板：<project_name> is a <utility/tool/feature> that allows <insert_target_audience> to do <action/task_it_does>.

您还可以添加另外一两行，但不要过多。

亮点

添加快速突出显示列表。以下是示例：

- Fast. See [benchmarks](#benchmarks) for more info
- Small. Only `1kb`
- etc.

先决条件

接下来要做的是列出先决条件。确保所有这些都包含在内（按重要性排序）：

1. 支持哪些操作系统（OS？OS's？）
2. 需要哪些依赖项和工具
3. 需要哪些知识

安装

显示安装命令。虽然程序员有神奇的能力，但复制粘贴仍然是大多数人的首选。

此外，如果有 CDN，请展示如何使用它的示例。

如果您有夜间/测试版本，也请展示如何安装它们。

用法

尽可能多地展示使用示例。展示最简单、最快捷的项目使用方法。很少有代码片段能够始终有效，因此如果没有，请务必提供多个示例。

如果您链接到文档，则可获得加分！

如何贡献，以及表彰贡献者

对于“如何贡献”部分，只需快速展示如何分叉、克隆和设置 repo，并链接到贡献文件以了解详细信息。

对于贡献者，你可以手动操作，也可以使用类似“所有贡献者”这样的工具

执照

如果人们一路走到这里，他们肯定对这个项目感兴趣并愿意成为贡献者（如果不是，他们应该在看完使用示例后就离开了）。所以，请注明他们使用的许可证。

现在你知道如何写一篇优秀的 README 了！感谢阅读！👋

（有趣的是：我曾经<esc> :wq发布过这篇文章🤣🤣）