我如何利用 Reddit 和 Twitter 让你的 README 文件更有效

我的故事

1. 信息丰富的视觉效果

2. 可导航性

3. 可扩展内容！

结论

由 Mux 主办的 DEV 全球展示挑战赛：展示你的项目！

我在大学期间学到的许多东西，多年来一直让我受益匪浅。其中最重要的一点是关于技术写作的（感谢我的 CS 787 教授）。

由此可见，技术写作的关键在于清晰简洁。技术工作的方方面面，无论是视觉内容还是文字，都应避免冗余和无关内容。

这并不意味着你的写作不应该精炼或冗长，而是指你应该传达相关信息。换句话说，直奔主题。

我的故事

这就引出了我一直在编写的 README 文件。我有一个代码仓库，我想让它对潜在用户更有吸引力。很多开源开发者都会遇到这种情况。我之前并没有太多编写高质量 README 文件的经验。

多年来使用 GitHub，我见过一些风格独特、视觉效果/动画炫酷的 README 文件，但现在我并不认为这总是改进 README 文件最有效的方法。

上周我在几个编程相关的Reddit子版块发帖，内容大概是“想请教一下关于我的GitHub README文件的建议/批评意见？”，总共发了大约五个帖子。此外，我还私信了几位经验丰富的开源开发者。

接下来的48小时里，我陆续收到了反馈，今天很高兴与大家分享。我整理了回复中最重要的三点。

1. 信息丰富的视觉效果

一张图胜过千言万语。按照这个逻辑，图片太多就意味着文字太多。例如，看看这个代码仓库。里面有很多图片，让仓库看起来杂乱不堪。这些图片真的都必要吗？过多的大幅图片会影响页面的导航体验。

图片非常重要，但前提是它必须有意义。没人喜欢阅读枯燥乏味的文字，但一两张品牌/商业图片就足够了。你的 README 文件应该成为潜在开发者了解项目用途的工具，而不是推销广告。

此外，与成熟、有条理的美学相比，过度刺激的图像可能会让潜在用户反感。

根据这些反馈，我调整了一些尺寸较大的图片的位置和大小。品牌图片最好控制在两张以内。其他图片/动画应该只用于帮助用户快速上手或理解项目目标。

顺便说一下，这是我正在编写中的 README 文件链接。如果您喜欢这篇文章，请在 GitHub 代码库上点个星标，非常感谢！

2. 可导航性

对于像 GitHub 页面这样的项目来说，组织性和易用性密不可分。用户很可能会多次参考你的 README 文件。对于开发者来说，README 文件是查找特定主题（例如安装、依赖项等）信息的一站式平台。

我认为，满足这种导航性要求的最有效方法是使用目录。许多中小型的高质量项目都有某种形式的目录，即使它比较简陋。

这样做有两个目的。首先，它方便潜在用户快速跳转到所需部分。其次，它为你的 README 文件提供了一个清晰的结构。读者在阅读过程中可以预览即将阅读的内容。这种结构使得 README 文件条理清晰、引人入胜。

这是一个可以自动为现有 Markdown 文档创建目录的工具。

3. 可扩展内容！

与其说这是反馈，不如说这是我根据反馈提出的建议。在有人专门向我推荐之前，我甚至都没想过要使用 Markdown 的这个功能。事实证明，你可以使用以下代码在 README 中创建可展开的章节：

<details>
<summary>Section Header!</summary>
<p>

Some information...

`# Here's some code`

</p>
</details>

在我的README文件中尝试了这种格式化方法后，我可以肯定地说，以后我会一直使用它。它使布局更加简洁美观。

正如我之前所说，没人喜欢阅读一大段文字。这项功能极大地提升了我的代码库的可读性。Markdown 的这个特性非常棒，它能在不丢失内容的前提下，显著减少 README 文件中的冗余信息。

用户无需离开页面即可了解特定主题的更多详细信息，只需点击下拉箭头即可。以下是我的具体实现示例，供您参考。

想要更深入地了解 Markdown 中的下拉菜单，请查看此 gist。

结论

感谢阅读！这三条建议肯定能提升你的 README 文件的有效性。记住，README 文件的核心目标是每一步都清晰简洁。

以上三条建议是我根据多方反馈挑选出来的。在未来的项目中，请务必考虑信息丰富的视觉效果、便捷的导航和可折叠的内容。

如有任何疑问或顾虑，请随时留言。我一定会尽快回复！