开放组织大使最近发布了开放组织成熟度模型，这是一个组织可以用来在五个特征上“升级”的框架：透明度、包容性、适应性、协作和社区。受我和我的大使同事为制作这个有价值的工具所做的努力的启发，我最近将成熟度模型概念应用于 README 开发。您可以在 此处找到 README 成熟度模型，作为我的 Feedmereadme 项目/改进世界 README 的运动的一部分。
基于单个文件的生成创建成熟度模型起初可能看起来有点过分。但是考虑到 README 作为大多数开源项目的入口点的重要性，以及许多开发人员对编写文档的厌恶，为这个关键项目元素提供入门和结构似乎不仅实用，而且至关重要。
更重要的是，由于开放组织通常依赖大量（且有效）的文档来以透明和负责任的方式完成其工作，因此审查、修订、重新评估文档的能力非常宝贵。README 成熟度模型旨在通过为您提供一个框架来评估五个不同“级别”的开发文档，从而帮助您的团队开发文档。
让我解释一下它们。
一级：“代码即文档”
在我 Twitter 消息的同温层中，没有人同意“代码就足够作为文档”。谷歌的 Kelsey Hightower 和 Lightbend 的 Viktor Klang 等思想领袖赞扬了技术作家将代码变成可理解的故事的工作。然而，仍然有太多人期望代码是开发人员愿意或能够提供的最佳文档。
最近，在与一位产品同事的交流中，我遇到了这种期望，他建议在与我的团队计划即将到来的错误审查时，我不要提及任何文档修复，以免人群感到害怕而避免参与。“如果我们假设开发人员会讨厌编写文档，那么他们就会反过来假设他们应该讨厌编写文档，”我说。然后我指着我的队友“Bob”，并向产品专家解释说，今年早些时候，Bob 曾激动地询问我们为什么需要在我们的仓库中编写任何内部 README，因为它们相当于“营销废话”。我指出，在敏捷环境中工作了将近一年，并且经常随叫随到之后，Bob 最近建议使用——什么？！——README 驱动开发来创建一个 Elasticsearch 插件。产品专家似乎对这个转变故事感到惊喜。
我们的错误审查产生了三条与文档相关的改进建议。
但是，让我们解决绝对讨厌编写文档的开发人员的问题。无论是由于写作障碍、矛盾心理，还是不知道该说什么，成熟度模型都通过从零（或接近零）开始来解决这些以及其他与 README 相关的焦虑来源。一级项目反映了以下情况
- 没有任何类型的 README 文本/几乎没有
- 没有安装、配置、运行细节
- 没有开发人员文档
- 没有补充文件，例如贡献者指南
- 没有构建状态信息，因此无法了解项目的当前状态
- 没有针对问题和/或拉取请求的建议平均响应时间
- 没有显示代码覆盖率或其他质量指标的徽章
- 可用的文本可能是过时的或非优先的
一级对于个人项目或实验来说是可以的。但是，对于公司托管的项目，它会带来一些声誉风险。您可能在向潜在的合作者和招聘人员发出信号，表明您的团队不重视文档。
二级：最简 README
所以，您想提供比空壳或完全空白多一点的文档。很好！成熟度模型考虑了烘焙最简、二级 README 的以下要素
- 关于项目的功能和用途的有限信息
- 针对用户的基本安装、配置、运行细节，可能未经测试且不完整
- 基本或没有开发人员文档
- README 中关于贡献的一行文字，但没有专门的文件
- 关于项目构建状态的一行文字，尽管它可能是过时的；或者没有构建状态信息
- 关于问题和/或拉取请求的平均响应时间的一行文字
- 没有显示代码覆盖率或其他质量指标的徽章
- 文本更新频率不高，可能已过时或不准确
在阅读上面的项目符号列表后，您可能想知道这样的 README 为潜在用户或贡献者提供了多少价值。答案是：不多。我建议直接跳到三级。这就是我们开始认真对待的地方。
三级：基本 README
在这里，您的 README 开始为您和您的工作说话——回答关键问题并提供关于项目用途和效用的重要背景信息。这是使您能够开始与更广泛的社区进行有意义的对话的级别。三级 README 提供
- 关于项目的功能、用途和目的的一些详细信息
- 针对用户的基本安装、配置、运行细节，经过测试且完整
- 针对潜在贡献者的基本文档
- 用于引导新贡献者的愿景声明或项目路线图
- 包含基本信息的 Contributing.md/.rst 文件
- 关于项目构建状态的一行文字，但最少：“正在开发中”或“稳定”
- 关于问题和/或拉取请求的平均响应时间的一行文字
- 至少一个显示代码覆盖率或其他质量指标的徽章
- 文本按月或按季度更新，因此可能存在不准确之处
提交给 Feedmereadmes 的大多数提交都带有介于此级别和上一级别之间的 README。通常，README 已过时或不完整；它带有用户说明，但没有针对开发人员的指南（或反之亦然）。贡献者指南是基本的，但可能过于简单，以至于会产生摩擦，而更详细的样式说明或经过用户测试的步骤可以避免这种情况。
这些项目中最常缺少的内容——即，“我可以自动化/机器人化自己，向所有申请人询问这些问题”——是关于项目目的的问题的答案：为什么项目存在以及它与现有解决方案的相似之处或不同之处。它是否实际产生了任何结果来证明其价值？这些问题的答案将我们带到下一个级别。
四级：有目的的 README
如果您真的想建立社区，并吸引大公司考虑参与其中，那么将您的项目展示为可行的产品可能会产生很大的影响。它不必花哨或带有商业广告，但确保您的四级 README 包含以下内容会有所帮助
- 关于项目的目的、功能和特殊特性/属性的详细信息
- 详细的用户安装、配置和运行说明，可能最近没有更新；关于常见错误以及如何解决它们的信息
- 针对潜在贡献者的详细文档
- 用于引导新贡献者的详细愿景声明或项目路线图
- 包含详细样式指南的 Contributing.md/.rst 文件
- 构建状态标识了项目的不完整和/或导致不稳定性的具体方面
- 关于问题和/或拉取请求的平均响应时间的明确信息
- 一个或多个显示代码覆盖率或其他质量指标的徽章
- 文本按月或按季度更新，因此可能存在不准确之处
在此级别，您正在定期进行文档更改并管理围绕响应时间和支持的期望。您已经涵盖了开发人员和用户说明，并已对其进行测试以确保它们是可理解的。您还预测了您的用户和贡献者可能会误入歧途的地方，并帮助他们克服障碍。最后，您已为我们五步 README 伟大之旅的最后一个级别做好准备。
五级：面向产品的 README
在这里，您需要小心地平衡“营销废话”和有价值的信息。您一流的五级 README 包括以下要素
- 关于项目的目的、功能和特殊特性/属性的详细信息，以便读者可以立即理解其特性和属性的用途和影响
- 包括用户评价和过去在实际开发情况中表现的证据
- 详细的用户安装、配置和运行说明，经过测试且是最新的；关于常见错误以及如何解决它们的信息
- 针对潜在贡献者的详细文档
- 用于引导新贡献者的详细愿景声明或项目路线图
- 嵌入式视觉辅助工具，如图表和演示
- 包含详细样式指南的 Contributing.md/.rst 文件
- 构建状态标识了项目的不完整和/或导致不稳定性的具体项目方面
- 关于问题和/或拉取请求的平均响应时间的明确信息
- 一个或多个显示代码覆盖率或其他质量指标的徽章
- 文本每周甚至每天更新，因此不太可能出现不准确之处
这些 README 利用视觉效果和用户反馈来强化其父项目有效地解决了技术解决方案。特别是视觉效果在展示项目运行方面有很大帮助。我们最成功的两个项目 SwiftMonkey 和 Fashion-MNIST 在首次发布时就利用了可视化和动画——使开发人员和非开发人员都可以访问它们。持续的文档改进和详细信息在开始时就解决了问题，减少了用户和贡献者的摩擦。
README 成熟度模型不是具体的规则手册；级别之间的界限是流动的。它们也可能提供改进空间，这就是为什么该模型是开源的并接受贡献。我通过创建和编辑文档学到的一个教训是，总有改进的空间。希望该模型为您提供了一个衡量您逐步改进的框架。
2 条评论