为什么有些开源项目代码质量一般却star过万，有些精品仓库却无人问津？答案往往藏在第一屏的文档里。我见过太多"幽灵项目"——代码写得漂亮，README却一片空白。作者假设用户会自己翻源码找答案，结果自然是没人用、没人贡献、没人记得。

想象你开发了一款出色的软件，却因为缺少文档而无人知晓、无法使用。不幸的是，这样的项目比比皆是。但你的项目不必如此。

此前我发表过《GitHub项目的最后1%：如何完美收尾》，其中README被列为第一项。是的，它就是这么重要，因此我决定深入探讨这个话题。

对于软件工程师而言，撰写规范文档是最关键的技能之一，没有任何借口可以跳过或将其视为可选项。写代码确实更有趣，但日后回头试图理解自己做过什么、为什么这么做，却没有任何参考，远比提前写几行清晰注释痛苦得多。

如果你希望作品被认可、被使用、被贡献，甚至被点赞，文档绝非可选项。它是人们首先看到的东西，也是他们留下或离开的原因。

本文不讨论文档体系的全部——那是个庞大话题，值得另文拆解。文档类型众多，各司其职。这里我们只聚焦最核心的一项：README。

职业生涯中我见过形形色色的README。有些优秀，有些平庸，少数近乎完美。但有一点始终成立：有一份包含实用信息的README，远比完全没有要好。你必须从某处开始，完美并非起点，而是持续精进的结果。

从业近十年，直到今天我看自己的README仍会想：还能更清晰、更一致、更好。你永远不会对文档完全满意，这正是关键所在——它需要持续打磨，如同代码本身。