修复文档，一次一个 README

GitHub 团队在其全新的开源调查中指出：“文档具有很高的价值，但经常被忽视，并且是建立包容和易于访问的社区的手段。” 基于 5,500 份回复，该调查显示，93% 的受访者表示“不完整或过时的文档是一个普遍存在的问题。” 然而，只有“60% 的贡献者很少或从不为文档做出贡献。”

对于任何在 GitHub 仓库中花费几分钟以上时间浏览的人来说，这些统计数据都不会令人惊讶。 你有多少次点击 GitHub 仓库，浏览 README，然后想：“听起来很有趣，但它实际上是做什么的？”

如果项目的创建者是你的同事，你可能能够亲自或通过聊天与他们跟进。 如果项目创建者身处地球的另一端，你可能会将你的问题发布为 GitHub issue。 但是，如果你时间紧迫，你很可能直接转向寻找另一个 README 提供了你解决所面临的技术挑战所需的保证的项目。 其他原因可能促使你放弃：该项目没有许可证，没有贡献指南，或者没有保证维护者会回复你的 pull request。 所有这些问题都很容易解决，并且可以为你的社区（或其他开放组织）招募新参与者带来显着的回报。 然而，稍微施展一下 Markdown 魔法却不知何故变成了事后才想到的事情。 可悲！

因此，几个月前，我决定解决这个问题。 我创建了 Feedmereadmes，一个旨在通过为想要 README 帮助的开源项目创建者提供免费的写作/编辑服务和项目分析，使世界上的 README 更具可读性的帮助交流平台。 它还为想要参与开源但又不确定从哪里开始的作家和编辑提供了贡献的机会。 在创建该项目时，我想创建一个让开发者和作家交流、协作和分享知识的地方，以便我们可以创建任何人都能普遍理解的 README。

我们需要你，Feedmereadmes

Feedmereadmes 的目标受众很广泛：没有编辑服务预算的个人项目创建者和小型团队。 Maintainer.io 是一家新公司，为希望为其开源计划增加润色和专业性的公司提供类似的服务（以及更多 - 请查看）。 他们的一位创始人运营着 Awesome README list，这是一个关于 README 的宝贵资源； 他不久前友好地将 Feedmereadmes 添加到列表中。

显然，像 Maintainer.io 和 Feedmereadmes 这样的努力满足了长期存在的需求。 对更好文档的呼吁早于 GitHub，并且鉴于 GitHub 的高速增长（2000 万个仓库并且还在增加），这种需求变得更加明显。

早在 2010 年，GitHub 创始人 Tom Preston-Warner 就以一篇仍然流行且仍然具有先见之明的文章“README 驱动开发”加入了这个话题，他在文章中倡导首先编写 README。 “首先。 就像在编写任何代码、测试、行为或故事或任何东西之前一样，”他写道。 “我知道，我知道，我们是程序员，该死的，不是技术作家！ 但你错了。 编写 Readme 对于编写好的软件绝对至关重要。 在你写出关于你的软件之前，你不知道你要编写什么代码。”

多年以后，对于许多人来说，文档仍然是 OSS 开发中被忽视的一部分。 结果是

• README 没有基本的安装/运行/配置说明，给潜在用户和贡献者造成了不必要的摩擦。
• README 没有解释项目背后的“为什么”和“如何”——项目为什么存在，它与类似项目的不同之处，创建者或其他人在生产中如何使用它，以及它的架构如何。
• README 要么太短，要么太杂乱。

2017 年 2 月，在 FOSDEM 上听 Rich Bowen 谈论文档的缺点和失败时，我开始思考什么可以减少世界上集体性的、文档产生的悲伤商数。 Rich 的演讲题为“阅读该死的说明书？ 也许你需要写一本更好的该死的说明书”，重点是 OSS 项目创建者和维护者需要倾听他们的受众并欢迎新手。 它鼓励听众“将整个项目社区视为其文档”——这种想法超越了“开发者不喜欢编写文档”的刻板印象（嘿，很多作家也不喜欢写作！）和“代码本身会说话”的神话。 “花点时间理解为什么人们会问你‘那个愚蠢的问题’，”Rich 告诉 FOSDEM 的人群。 “通常问题是你的文档很糟糕或令人困惑。”

受到 Rich 演讲的鼓舞，我在展厅里找到了他，感谢他的启发。 当我们聊天时，一个想法浮现出来：为项目创建者提供免费的写作和编辑服务。 一小段路程和一个比利时华夫饼之后，Feedmereadmes 从 GitHub 的子宫中诞生了，像婴儿一样哭闹着以解决它的饥饿感。

Feedmereadmes 如何工作（以及为谁服务）

对于项目创建者来说，第一步是通过 “Issues”功能链接项目的 README。 他们也可以将他们的 README 链接推文至 @feedmereadmes，然后我为他们创建一个 issue。

接下来，我编辑和校对 README。 在 pull request 消息中，我向维护者提出一些问题，以帮助他们澄清他们的项目目的。 如果不清楚他们为什么创建该项目、项目如何运作以及项目解决了什么问题（以及一些支持证据描述项目如何解决实际问题），我会包含这些问题以及一些支持资源以提供更多背景信息。 Mozilla 的 Open Canvas、18f 的开源指南，以及我们在 Zalando 创建的 README 和 产品分析 模板是我的常用工具。

当作家和编辑想要参与时，我只需将他们引导到 Issues 跟踪器，并邀请他们认领一个项目来提供帮助。 我在那里创建的 README 包含一个针对初学者的 GitHub 教程的链接。 我还加入了一些关于为什么免费工作的理由。 作为一名前记者、博主和文案撰稿人，我对许多公司和实体提供“免费曝光”作为补偿这一事实非常敏感。 对于努力靠写作谋生的作家来说，“免费宣传”无法支付房租或印度菜。 考虑到这一点，我加入了以下说明

[T] 仔细考虑一下你为什么要贡献你的写作和编辑技能，以使世界上的 README 更具可读性。 可能是为了增加你对技术和开源的了解； 与有创意的人合作； 以你认为简单，但他们可能认为困难的方式帮助苦苦挣扎的开发者改进他们的项目； 或者考虑到不同的工作前景来建立你的作品集。 也许你被 FOSS 的自由交流和信息共享的精神所吸引。 这些只是我们世界各地许多人在晚上和周末在电脑前工作，无偿工作的一些原因。

我还添加了一条帮助我在工作中获得更大成就感的建议：“去温暖的地方”。 换句话说，帮助那些欣赏你并让你感到自己属于那里的人。 如果项目创建者利用你或让你感到不舒服，请寻找另一个项目。 寻找让你感到被尊重、被欣赏和“他们中的一员”的合作者。 不要退而求其次。

自从该项目在 2 月份启动以来（现在是 6 月），我添加了另一个目标受众：想要为开源做出贡献的产品经理和专家。 这个想法，就像项目本身一样，是偶然产生的：通过与一位才华横溢的同事和产品专家进行的非正式对话，他正在寻找进入 GitHub 的切入点。 我们尚未找到他开始贡献的机会，但他为该项目带来的业务见解可能真的可以帮助我们的受众提升他们的工作。

Feedmereadmes（说真的，我是认真的）

不幸的是，Feedmereadme 的受众目前仍然很小。 一个原因可能是，需要更好文档的项目可能不太可能主动寻求支持，甚至去寻找支持。 考虑到这一点，我最近开始主动联系项目，提供帮助。 虽然一些项目创建者没有回应，但大多数人很高兴收到另一位愿意为他们的工作投入时间的贡献者。

至于那些已请求 README 帮助的项目，我可能可以传达的最大教训是：为与文档相关的贡献创建一个“EZPass”选项。 你可以通过允许贡献者 fork 并修复你的 README 来做到这一点。 想象一下，一位非常敏锐但新手技术作家来到你的项目，充满热情地编辑你所有未大写的句子和拼写错误的单词，但看到一个安装软件包并遵守旨在规避专制和喋喋不休的机器人的规则的要求列表。 那个人很可能会离开； 你已经让他们不知所措了。

采取更以 README 驱动的开发方法也将有助于项目创建者掌握文档创建，并可能提高整体项目可访问性。 代码并不总是会说话。 即使对于我们这些编写代码的人来说，在一段时间过去，我们忘记了在那一刻灵感乍现时我们究竟在想什么之后，代码也常常不会说话。 正如我的同事 Bill de hÓra 所说，“文档是一项高杠杆率的活动，它可以让你专注于结果和你想要实现的目标。 文档远非开销，而是通过为你的用户和同事提供上下文来理解项目的作用和原因来获得回报。”

即使你不同意我的同事 Bill 或 Tom Preston-Warner 的观点，你仍然可以确保你的 README 在你想要处理它们的程度上是用户友好的。 我建议将“用户”广泛定义为包括你的同事、你的语言社区、你的经理、你的偶像、记者、匆忙的 FOSS 瘾君子和你的父母。 （你希望你的父母为你感到骄傲，对吧？ 通过让他们能够理解你在做什么来帮助他们。 讲述一个其他人可以理解的故事。）

结论

虽然“改进我的文档”可能仍然看起来像是开源开发中的“戒烟”或“每天跑步”，但我们项目创建者（93%！）知道我们需要这样做。 然而，我们中的许多人并没有将其作为优先事项。 嘿，没关系，数百万 GitHub 贡献者——当你准备好了，我们就在这里。