本文共 3222 字,大约阅读时间需要 10 分钟。
链表查询和分步查询那个更好
最近发布了 ,该框架可供组织用来“升级”五个特征:透明性,包容性,适应性,协作性和社区性。 受我的大使和我为生产这种有价值的工具而投入的努力的启发,我最近将成熟度模型概念应用于README开发。 您可以在找到README成熟度模型,这是我的项目/计划的一部分, 是改善全球自述文件。
首先,基于单个文件的生成来创建成熟度模型似乎有点过头了。 但是考虑到大多数开源项目的 ,以及许多开发人员对编写文档的厌恶,为这一关键项目元素提供和结构似乎不仅实用,而且至关重要。
而且,由于开放组织经常依靠大量(有效的)文档来透明和负责地完成其工作,因此具有审查,修订,重新评估文档的能力非常有价值。 README成熟度模型旨在通过为您提供在五个不同的“开发级别”评估文档的框架来帮助您的团队进行开发。
让我解释一下。
在我的Twitter feed的回声室中,没有人同意“代码足以说明文档”。 诸如Google的Kelsey Hightower和Lightbend的Viktor Klang之类的思想领袖赞扬技术作家的工作,他们将代码变成了可理解的故事。 但是,仍然有太多人希望代码是开发人员愿意或能够提供的最佳文档。
最近,在与产品同事进行交流时,就产生了这种期望。在产品交流中,我建议与我的团队一起计划即将到来的bug扑朔迷离,我保留了所有有关文档修复的内容,以免使人群感到恐惧并避免参与。 我说:“如果我们假设开发人员会讨厌编写文档,那么他们就会以为他们应该讨厌编写文档。” 然后,我指向我的队友“鲍勃”,并向产品专家解释说,鲍勃在今年早些时候激动地问为什么我们需要在我们的仓库中编写任何内部自述文件,因为它们相当于“营销废话”。 我注意到在敏捷环境中工作了将近一年并定期待命之后,Bob最近建议使用来创建Elasticsearch插件。 产品专家似乎对这个转变故事感到惊喜。
我们的bug bash提出了三个与文档相关的改进建议。
但是,让我们向绝对讨厌编写文档的开发人员致辞。 无论是由于作者的阻拦,矛盾,还是不知道说什么,成熟度模型都从零(或接近零)开始解决了这些以及其他与README相关的焦虑的根源。 一级项目反映以下内容:
一级适合个人项目或实验。 但是,对于公司托管的项目,这会带来一些声誉风险。 您可能会向潜在的合作者和应聘者发信号,表示您的团队不重视文档。
因此,您想要提供的文档多于裸露的骨架或完全空白。 好! 成熟度模型考虑以下成分来烘焙最低限度的二级自述文件:
阅读以上项目符号列表后,您可能想知道这样的README给潜在的用户或贡献者带来多少价值。 答案:不多。 我建议跳到第三级。 那就是我们变得认真的地方。
这是您的自述文件开始为您和您的工作说话的地方-回答关键问题并提供有关项目目的和用途的必要背景信息。 此级别使您能够与更广泛的社区开始有意义的对话。 三级自述文件提供:
Feedmereadmes的大多数提交都附带了此级别与上一个级别之间的README。 自述文件经常过时或不完整; 它带有用户说明,但没有针对开发人员的指导(反之亦然)。 贡献者准则是基本准则,但可能会极少出现摩擦,以至于避免更详细的样式注释或用户测试的步骤。
什么是最经常从这些项目中,即失踪,“我可以自动/ botify自己要问这些问题,所有申请” -are回答有关项目的目的的问题: 为什么项目存在,它是如何相似或现有的解决方案不同。 它实际上产生了任何证明其优点的结果吗? 对这些问题的回答将我们带入了一个新的高度。
如果您真的想建立社区,并诱使大公司考虑参与其中,那么将您的项目作为可行的产品来展示可能会有所作为。 它不一定要精巧或附带商业广告,但请确保您的四级自述文件包括以下帮助:
在此级别,您将定期更改文档并管理响应时间和支持方面的期望。 您已经介绍了开发人员和用户说明,并对其进行了测试,以确保它们易于理解。 您还已经预见了用户和贡献者可能会误入歧途,并帮助他们克服了障碍。 最后,您已经为进入README出色体验的五个步骤而迈向了最后一步。
在这里,您需要谨慎地在“营销废话”与有价值的信息之间取得平衡。 一流的五级自述文件包括以下元素:
这些自述文件利用视觉效果和用户反馈来强调其上级项目有效地解决了技术解决方案。 特别是视觉效果在展示实际项目方面大有帮助。 我们最成功的两个项目和在首次发布时就利用了可视化和动画,使开发人员和非开发人员都可以使用它们。 持续的文档改进和详细的信息从一开始就解决了问题,从而减少了用户和贡献者之间的摩擦。
README成熟度模型不是具体的规则手册; 水平之间的边界是可变的。 它们还可能提供改进的空间,这就是该模型是开放源代码且愿意捐款的原因。 我从创建和编辑文档中学到的一课是,总有改进的余地。 希望该模型为您提供一个衡量您进行中的改进的框架。
翻译自:
链表查询和分步查询那个更好
转载地址:http://ygbzd.baihongyu.com/