如果说代码是心脏，那么医生就是声音

怎么样，书呆子们？实话实说：如果说代码是开源软件的心脏，那么文档就是声音。它是你的项目与世界对话的方式。

这就是残酷的事实--我见过很多出色的项目因为没有人知道如何使用它们而夭折。没有文档，你的代码只是......噪音。

是什么让文档变得伟大？

好的文档不是放之四海而皆准的。它是一个系统。你至少需要

• 用户指南→ 让新人从零开始工作的入职体验。
• 应用程序接口文档→ 希望集成您的项目的开发人员的生命线。
• 贡献指南→ 促进合作的社区手册。

如果没有这些，你的项目就像递给别人一个正面没有图片的拼图盒。

文件为何决定采用与否

想象一下：你发现了一个开源工具，它可以解决你所有的问题。你很兴奋。你安装了它。然后......鸦雀无声。没有说明，没有示例，只有一个写着 "祝你好运 "的 README。

你会反弹。每个人都会。

看看 React 或其他重量级开源软件。他们的文档和代码一样精致。这并非偶然。清晰的文档不仅能帮助用户，还能培养拥护者。当开发人员可以在不碰壁的情况下使用你的库时，他们就会传播你的文档。

最难的部分编写和更新文档

是啊，编写文档是一件很困难的事情。你需要

• 清晰而不生涩
• 示例，而不仅仅是讲述
• 逻辑结构合理，以便人们快速找到答案

但最难的部分是什么？不断更新文档。过时的文件比没有文件更糟糕。这就像使用一个 GPS，它会把你送到三年前就关闭的企业。令人沮丧。

跳过文档，沉入项目

文档不会让你在开发者聚会上赢得高分。但是如果没有文档，你就只能在流沙上进行建设。它是其他一切的基础。

那就写出来。维护它。擦亮它。因为如果你想让你的代码活下去，你的文档就必须会说话。

下一个E 代表生命终结

敬请期待下一期《开放源码软件 ABCs》，我们将讨论 "E "代表 "生命终结"（End of Life）--优秀软件的死亡归宿，以及为什么你应该关心它。

在此之前呢？保持代码整洁，文档更加整洁。

‍