如何编写出色的 GitHub README

我读完了能找到的最早的 README 文件。它由威廉·J·厄尔于 1975 年在伊利诺伊大学芝加哥分校计算机科学系撰写。虽然内容略显枯燥，但即使在 44 年后，它仍然出奇地具有可读性。“由于编译器中的一个 bug，此函数无法正确编译”。

README 反映了仓库的维护方式。好的 README 并不一定意味着项目活跃、无 bug、测试完美。但它表明项目所有者关心你，你作为用户（或未来的维护者）。好的 README 会告诉你使用和参与项目所需的一切信息。它不仅能推销项目，还能同时尊重访问者的时间，让他们知道是否需要其他解决方案。

当你的 GitHub 个人资料作为应用程序的一部分时，README 的重要性体现在另一方面。它展现了技术写作能力——良好的沟通能力以及编写软件相关文档的能力。指望别人深入研究你的代码，却不提供项目抽象概念的解释，这无疑是一个很大的挑战。

清晰的描述

人们应该无需阅读一行代码就能使用您的软件。

python-ml-project-for-cat-lovers-2首先，将 GitHub提供的默认标题改为Cat Crawler - Classify Cat GIFs。下一步是用最简单的形式解释你的项目。很多人会在最顶部用一行代码。

下载并索引猫咪 GIF 的机器人

随着您在潜在客户描述中添加更多内容，认知超载的可能性也会随之增加。精简语言后，请使用标题、换行符和空格进一步分隔。（新段落和<br>换行符之间应留出两行。备忘单。）不要回避产品徽标和屏幕截图。与其他技术文档不同，多媒体在这里效果很好。对于比较深奥的存储库，添加背景阅读部分会有所帮助。

如果你的仓库有趣或轻松，那么你的描述应该体现这一点！Strunk & White有他们自己的市场，但互联网也是酷炫程序员发挥创造力的聚集地。值得一提的是，如果客户不付费，网站就会逐渐消失，直到某个日期完全不可见。

用法

用户如何使用你的项目？如果是 API，请提供一段包含最基本交互的代码。完整的文档可以放在页面下方或其他位置。facebook /react提供了一个示例来展示它们的用法——这是用户使用 React 的最简单的方式。使用单引号引用代码，使用三个反引号另起一行引用代码块。将语言代码放在前三个反引号之后，以便突出显示。

function HelloMessage({ name }) {
  return <div>Hello {name}</div>;
}

ReactDOM.render(
  <HelloMessage name="Taylor" />,
  document.getElementById('container')
);

展示本次交互的输出。如果可以用 GIF 动图，那就用吧！GIF 动图易于人类理解，并且能够向读者传递大量数据。alexfoxy /laxxx，一个用于制作流畅网页动画的库，在这方面做得非常出色。

我使用开源工具ShareX来制作 GIF。它很简单，只需选择屏幕上的区域即可。我推荐的另一个解决方案是LICEcap ，它也是开源的。

安装

希望访问者在看到你的项目运行后，会想要安装它。本节有时被称为“入门”。每个项目都应该包含这一部分，即使它只是一个npm install catcrawler……如果它是一个静态网站，那就这么说吧！host the parent dir on a webserver假设你已经掌握了基本工具。你不需要解释“pip或npm”是什么，但你应该列出在新设置中要运行的每个命令。

DEV有一个详尽的章节，教你如何构建并运行，如果你想要更容易上手，这是一个很好的参考模型。最好启动一个虚拟机，并尝试复制你的安装指南——假设你没有自动构建测试来帮你完成这件事。

徽章

GitHub 徽章主要由徽章/盾牌标准化，是访客向下滚动时首先看到的内容之一。构建状态徽章描述了项目的稳定性。其他徽章可能显示​​仓库的活跃度（每月提交次数）或维护者数量。它们并非强制性的，但与 GIF 动图一样，是一个巨大的奖励。

shields.io有一个 API 可以创建你自己的徽章，他们还有一个好用的 npm包。我几周前开始用它，不到一小时就创建并运行了一些徽章！另一个 npm 替代方案是badger。Python 有Google 的pybadges 。

如果您想获得自己的第一枚build: passed徽章，我在 DEV 上写了一篇文章，指导您在 GitHub 上开始进行持续集成。

贡献

如果您正在寻找贡献者，那么贡献者专区会很有帮助，也很受欢迎。GitHub 有一个将文件添加到根目录的标准CONTRIBUTING.md。这可能包括行为准则以及查找问题和构建拉取请求的通用指南。很多初学者对帮助开源项目的过程感到焦虑，而逐步指导他们可以缓解一些焦虑。如果您不确定从哪里开始，我最近看到了一个行为准则生成器，我觉得它非常简洁。我知道我的一些朋友只会支持那些对维护者互动有严格指导和规则的仓库。

执照

当我在工作中寻求解决方案时，许可证是我首先要考虑的。通过 GitHub 创建仓库时，可以选择一个许可证，它会LICENSE.md为你生成一个文件。GitHub 上也有一个关于此文件的页面——他们是choosealicense.com的创建者，这是一个很棒的指南，可以引导你了解所有选项。我个人使用 MIT 许可证来处理我的开源代码。有些人对许可证持有强烈的意见，尤其是在GPL许可证方面。“任何对 GPL 许可证代码的修改或包含（通过编译器）GPL 许可证代码的软件也必须遵循 GPL 许可证，并附上构建和安装说明。”

模板

市面上有 很多README 模板。它们在紧急情况下非常有用，但我发现小型项目不太适合这种模板，而且最终的文本会显得有些冷冰冰。成熟的项目更适合使用模板 ，但考虑到开发人员可能在软件上投入的时间，定制解决方案还是值得的。

这是我最喜欢的，因为它直截了当，并且有两个关于测试的小节。如果你有任何测试，应该在你的 README 中提及。克隆项目时，我首先会运行测试，以确保我的设置已准备好进行开发。

其他部分

完成所有重要章节后，尽情填写你的 README 文件吧。我可能属于少数，但我喜欢浏览 GitHub 寻找新东西并探索它们的构建方式。我欣赏包含大量示例代码的详细代码库。对我来说，参与一个项目，重要的是看到维护者至少和我一样关心项目。

探索编程语言的流行趋势，了解标准布局。想要获得灵感，可以看看我最近最喜欢的两个：Gatsyby和lax.js。最重要的是，让你的文档更具感染力。

与 150 多名订阅我的关于编程和个人成长的新闻通讯的人一起！

我发布有关科技的推文@healeycodes。