The following text is a partial translation of the original English article, performed by ChatGPT (gpt-3.5-turbo) and this Jekyll plugin:
一段时间前我写了一篇博客文章《一个开放的代码库还不是一个开源项目》，在那里我提出了几个好的开源存储库/项目的重要特质。其中之一就是良好编写的README文件。在这里，我将尝试给出一些建议，关于如何创建一个好的README文件以及需要避免的错误。希望对你有所帮助。
我将按照这些元素应该出现的顺序，列出README中需要包含的所有内容。
为什么要包括这些？标题已经在您的存储库URL中，项目描述在GitHub的副标题中了。为什么要重复呢？相反，可以在logo后面立即列出徽章的列表。
请注意 logo 后面的空行。不要忘记在 height 属性中指定图像的大小。你可以跳过 width，因为对于 HTML 来说只需要一个维度就足够了。不要将其高度大于 100px。
您需要它们，就如我之前所说的一样。但问题是如何将它们放置在README中。每行最多只能放置五个徽章。然后用一个空行分隔每行。请看我们的zold-io/zold repo中的实例。
您应该以某种逻辑将它们分组在行内。我会按照技术细节的级别进行分组。第一行是关于CI、代码覆盖率和代码质量的。第二行更多关于管理等等。这取决于您，但请确保同一行中的所有徽章高度相同！如果某个徽章高度与其他所有徽章不同，请将其放在单独的一行，但绝不要将两个高度不同的徽章放在同一行上！
另外，请记住只有在极少数特定情况下（例如徽章）才允许超过80个字符的行。将您的README文档视为源代码的一部分。使其格式正确且优雅。行的宽度是使您的文档看起来更好的格式化规则之一。八十个字符。就是这样。
徽章之后的第一段应该解释产品的内容。注意：一个段落，不是一页的文字。你应该将产品描述放在一个单独的段落中。这里不要使用项目符号，不要换行，不要缩进。只需要一段简单的纯文本。
请注意，目前还没有标题。只有一个徽标、几行徽章和一些简单的文本，描述了产品的信息。您可以（而且应该）在此处使用Markdown，并将读者指向任何相关的博客文章、YouTube视频或其他内容，但请确保将整个想法放入一个段落中。
然后，没有任何标题，你直接进入了如何使用你的宝贝的要点，作为一个对这个版本库完全不熟悉的新手。我只是打开了这个页面，因为我的一个朋友告诉我它很棒，我想知道它是否值得或者我应该立刻关闭它。你还有我的注意力60秒。告诉我如何尝试它！就像这样：
然后，您运行它并按照说明进行操作：
应该清楚该做什么。如果不清楚，请在我们的Telegram聊天室中向我们提问。
注意格式。我不缩进任何内容，并且使用三个撇号进行代码示例的格式化。您应该遵循相同的方式。使用单个空行分隔文本块。
这是您README的正文部分。确切的内容取决于您的具体业务情况和产品的性质。然而，无论产品如何，都有一些建议。
首先，不要用README替换自动生成的Javadocs（或者您在其他语言中使用的文档）。README不是您存储库中所有内容的用户文档。有其他适合放置这些文档的地方。您可以在这里解释一些最有趣的用例。可以参考我们在yegor256/takes项目中的做法。
第二，请使用二级标题（Markdown中的##）开始每个用例，并尽量避免使用三级标题（###）。我需要再次强调四级标题是绝对禁止的吗？当然了，还有一点，不要缩进。无论是文本段落还是标题，始终将文本行从最左边位置开始。
第三，请记住您的产品很快会发生变化，您不想始终记得在README文件的哪个位置需要更改什么。您希望您的README尽可能简短，并保持高层次性。因此，如果可能的话，请避免具体细节，并将读者重定向到自动生成的文档的相关部分。
第四，请尽量使用少的词语。没有人会对您的散文感兴趣超过几秒钟，而且仅仅是为了了解如何使用您的产品或进行一些更改。不要将注意力集中在自己身上，我们不关心您。将注意力集中在我们和我们的需求上。告诉我们它是如何工作的，并称其为README。不要有哲学，没有散文。将这些内容留给您的博客和Twitter。
开始用一个小节标题“如何贡献”来说明创建拉取请求到你的代码库需要做些什么。想象你正在与一个初级开发人员交谈，他甚至不知道Java和Maven是什么（如果你的项目使用它们的话）。你应该解释如何安装适当的工具，如何构建项目，如何进行更改，如何以热加载模式运行它（当我正在进行更改并立即在屏幕上看到它们时），如何创建分支，并解释提交分支后会发生什么。
不要太啰嗦。实际上，尽量简洁。在可能的情况下，总是将读者引导至这些工具的文档或一些博客文章，这些文章解释得更好。请参考Ruby的README中的示例。页面底部的简短文本解释了必须安装的内容（提供了安装教程的链接），如何在本地运行应用程序，如何运行构建，如何运行单个单元测试以及如果测试不通过应该怎么做。这是相当简洁的，我相信很容易理解。
你不希望潜在的贡献者放弃。这就是为什么整个README中的这一部分是最重要的。确保你的文字是针对初级程序员的，而不是针对你自己的。正如他们所说，你的奶奶应该能够理解你在这里说的话。
不要教育我们。我们对于你使用的框架或Docker（为了运行你的东西而需要）不感兴趣。我们只想运行你的东西，做一些更改，获得新版本，然后离开。所以，请不要告诉我“首先，你必须学习Docker。”不，我不需要。如果需要，我自己早就学会了。告诉我如何在这个特定情况下使用它，并省去其余所有的内容。
GitHub有一个特殊的标签“releases”用于此功能。不需要在README中重复提及。只需确保您的“releases”标签包含足够的信息和足够的二进制文件以供下载。在README中不要提到它们。
GitHub会自动在您的存储库的根目录中找到LICENSE.txt文件并理解该许可证。只需创建该文件，不要在README中提及许可证，那只是纯粹的噪音。如果我想知道许可证是什么，我知道该点击哪里。
这是 GitHub 之前的一个东西。我建议你依赖于“releases”标签，并把你想要告诉我们的一切都保留在那里。一些旧项目会维护更改日志，例如rubocop-hq/rubocop。我不认为这是一个好主意。
GitHub在每个存储库中都有一个特殊的选项卡，称为“贡献者”。没有理由在README文件中重复列出这个列表。然而，有一个原因：帮助贡献者宣传自己。在这种情况下，我建议创建一个名为“致谢”的部分（带有标题），列出最活跃的贡献者及其博客URL、Twitter账户等等。
如果你没有要致谢的人，不要告诉我们贡献者是谁而制造噪音。我们知道他们，GitHub会告诉我们。
附注：这是我喜欢的一些README的简短列表，它们不是我的（如果你认为你的也不错，将其发送给我，我会进行评估，并可能将其添加到这个列表中）。
- “Vatavuk/verano-http” should be translated as “Vatavuk/verano-http”.
Translated by ChatGPT gpt-3.5-turbo/42 on 2023-12-17 at 15:56
