链表查询和分步查询那个更好_有关更有效文档的分步指南-CSDN博客

链表查询和分步查询那个更好

开放组织大使最近发布了开放组织成熟度模型，该框架可供组织用来“升级”五个特征：透明性，包容性，适应性，协作性和社区性。受我的大使和我为生产这种有价值的工具而投入的努力的启发，我最近将成熟度模型概念应用于README开发。您可以在此处找到README成熟度模型，这是我的Feedmereadme项目/计划的一部分，目的是改善全球自述文件。

首先，基于单个文件的生成来创建成熟度模型似乎有点过头了。但是考虑到README作为大多数开源项目的切入点的重要性，以及许多开发人员对编写文档的厌恶，为这一关键项目元素提供入门和结构似乎不仅实用，而且至关重要。

而且，由于开放组织经常依靠大量（有效的）文档来透明和负责地完成其工作，因此具有审查，修订，重新评估文档的能力非常有价值。 README成熟度模型旨在通过为您提供在五个不同的“开发级别”评估文档的框架来帮助您的团队进行开发。

让我解释一下。

一级：“代码就是文档”

在我的Twitter feed的回声室中，没有人同意“代码足以说明文档”。诸如Google的Kelsey Hightower和Lightbend的Viktor Klang之类的思想领袖赞扬技术作家的工作，他们将代码变成了可理解的故事。但是，仍然有太多人希望代码是开发人员愿意或能够提供的最佳文档。

无论是由于编写者的阻拦，矛盾，还是不知道该说些什么，成熟度模型都可以解决这些以及与README相关的焦虑的其他来源。

最近，在与产品同事进行交流时，就产生了这种期望。在产品交流中，我建议与我的团队一起计划即将到来的bug扑朔迷离，我保留了所有有关文档修复的内容，以免使人群感到恐惧并避免参与。我说：“如果我们假设开发人员会讨厌编写文档，那么他们就会以为他们应该讨厌编写文档。” 然后，我指向我的队友“鲍勃”，并向产品专家解释说，鲍勃在今年早些时候激动地问为什么我们需要在我们的仓库中编写任何内部自述文件，因为它们相当于“营销废话”。我注意到在敏捷环境中工作了将近一年并定期待命之后，Bob最近建议使用README驱动的开发来创建Elasticsearch插件。产品专家似乎对这个转变故事感到惊喜。

我们的bug bash提出了三个与文档相关的改进建议。

但是，让我们向绝对讨厌编写文档的开发人员致辞。无论是由于作者的阻拦，矛盾，还是不知道说什么，成熟度模型都从零（或接近零）开始解决了这些以及其他与README相关的焦虑的根源。一级项目反映以下内容：

否/几乎没有任何形式的自述文本
没有安装，配置，运行细节
没有开发人员文档
没有免费文件，例如贡献者指南
没有构建状态信息，因此无法了解项目的当前状态
没有对问题和/或请求请求的建议平均响应时间
没有徽章显示代码覆盖率或其他质量指标
可用的文字可能已过时或不优先

一级适合个人项目或实验。但是，对于公司托管的项目，这会带来一些声誉风险。您可能会向潜在的合作者和应聘者发信号，表示您的团队不重视文档。

第二级：最低限度的自述文件

因此，您想要提供的文档多于裸露的骨架或完全空白。好！成熟度模型考虑以下成分来烘焙最低限度的二级自述文件：

有关项目功能和目的的有限信息
用户的基本安装，配置，运行详细信息，可能未经测试且不完整
基本或无开发人员文档
自述文件中有关贡献的一行，但没有专用文件
关于项目的构建状态的一行，尽管可能已过时；或没有构建状态信息
关于发布和/或请求请求的平均响应时间的一行
没有徽章显示代码覆盖率或其他质量指标
文本不经常更新，可能过时或不正确

阅读以上项目符号列表后，您可能想知道这样的README给潜在的用户或贡献者带来多少价值。答案：不多。我建议跳到第三级。那就是我们变得认真的地方。

第三级：基本自述文件

这是您的自述文件开始为您和您的工作说话的地方-回答关键问题并提供有关项目目的和用途的必要背景信息。此级别使您能够与更广泛的社区开始有意义的对话。三级自述文件提供：

有关项目功能，用途和目的的一些详细信息
基本的安装，配置，用户的运行详细信息，经过测试且已完成
潜在贡献者的基本文档
新加入贡献者的愿景声明或项目路线图
具有基本信息的Contributing.md/.rst文件
关于项目的构建状态的一行，但最少：“开发中”或“稳定”
关于发布和/或请求请求的平均响应时间的一行
至少一个徽章，显示代码覆盖率或其他质量指标
文本每月或每季度更新一次，因此可能存在错误

Feedmereadmes的大多数提交都附带了此级别与上一个级别之间的README。自述文件经常过时或不完整；它带有用户说明，但没有针对开发人员的指导（反之亦然）。贡献者准则是基本准则，但可能会极少出现摩擦，以至于避免更详细的样式注释或用户测试的步骤。

在我的Twitter feed的回声室中，没有人同意“代码足以说明文档”。

什么是最经常从这些项目中，即失踪，“我可以自动/ botify自己要问这些问题，所有申请” -are回答有关项目的目的的问题： 为什么项目存在，它是如何相似或现有的解决方案不同。它实际上产生了任何证明其优点的结果吗？对这些问题的回答将我们带入了一个新的高度。

第四级：有目的的自述文件

如果您真的想建立社区，并诱使大公司考虑参与其中，那么将您的项目作为可行的产品来展示可能会有所作为。它不一定要精巧或附带商业广告，但请确保您的四级自述文件包括以下帮助：

有关项目目的，功能和特殊功能/属性的详细信息
详细的用户安装，配置和运行说明，这些更新可能会或可能不会最近更新；有关常见错误以及如何解决这些错误的信息
潜在贡献者的详细文档
新的贡献者入职的详细愿景声明或项目路线图
具有详细样式指南的Contributing.md/.rst文件
生成状态标识项目的不完整和/或引起不稳定的特定方面
清除有关对问题和/或请求请求的平均响应时间的信息
一个或多个显示代码覆盖率或其他质量指标的徽章
文本每月或每季度更新一次，因此可能存在错误

在此级别，您将定期更改文档并管理响应时间和支持方面的期望。您已经介绍了开发人员和用户说明，并对其进行了测试，以确保它们易于理解。您还已经预见了用户和贡献者可能会误入歧途，并帮助他们克服了障碍。最后，您已经为进入README出色体验的五个步骤而迈向了最后一步。

第五级：面向产品的自述文件

在这里，您需要谨慎地在“营销废话”与有价值的信息之间取得平衡。一流的五级自述文件包括以下元素：

有关项目目的，功能和特殊功能/属性的详细信息，以便读者可以立即了解其功能和属性的有用性和影响
包括用户推荐书和实际开发情况下过去表现的证据
详细的用户安装，配置和运行说明（已测试和最新）；有关常见错误以及如何解决这些错误的信息
潜在贡献者的详细文档
新的贡献者入职的详细愿景声明或项目路线图
嵌入式视觉辅助工具，例如图表和演示
具有详细样式指南的Contributing.md/.rst文件
生成状态标识不完整和/或引起不稳定的特定项目方面
清除有关对问题和/或请求请求的平均响应时间的信息
一个或多个显示代码覆盖率或其他质量指标的徽章
文本每周或每天更新一次，因此不太可能出现错误

这些自述文件利用视觉效果和用户反馈来强调其上级项目有效地解决了技术解决方案。特别是视觉效果在展示实际项目方面大有帮助。我们最成功的两个项目SwiftMonkey和Fashion-MNIST在首次发布时就利用了可视化和动画，使开发人员和非开发人员都可以使用它们。持续的文档改进和详细的信息从一开始就解决了问题，从而减少了用户和贡献者之间的摩擦。

README成熟度模型不是具体的规则手册；水平之间的边界是可变的。它们还可能提供改进的空间，这就是该模型是开放源代码且愿意捐款的原因。我从创建和编辑文档中学到的一课是，总有改进的余地。希望该模型为您提供一个衡量您进行中的改进的框架。