hbuilder自述文件

GitHub团队在其全新的开源调查中指出：“文档受到高度重视，经常被忽视，并且是建立包容性和可访问性社区的一种手段。” 根据5500个反馈，调查显示93％的受访者表示“文件不完整或过时是一个普遍的问题”。 但是，只有“ 60％的贡献者很少或从未贡献过文档”。

这些统计信息不会使花了几分钟时间点击GitHub存储库的任何人感到惊讶。 您单击了GitHub存储库多少次，浏览了README，然后想到：“听起来很有趣，但是它实际上有什么作用？”

如果项目的创建者是您自己的同事，则您可以亲自或通过聊天与他们进行跟进。 如果项目创建者在地球的另一端，那么您可能将问题发布为GitHub问题。 但是，如果您时间紧迫，您很可能会继续寻找另一个项目，其README文件为您提供了解决所面临的技术难题所需的保证。 其他原因可能促使您继续进行下去：该项目没有许可证 ，没有提供任何指导方针，或者不能保证维护者会响应您的请求 。 所有这些问题都很容易解决，并且在您的社区（或其他开放组织）努力招募新参与者时可以大有作为。 然而，以某种方式使用Markdown魔术却成为事后的想法。 伤心！

所以几个月前，我决定解决这个问题。 我创建了Feedmereadmes ，这是一个帮助交流，旨在通过向需要README的开源项目创建者提供免费的编写/编辑服务和项目分析，使世界上的README更具可读性。 它还为想要参与开源但不确定从何入手的作家和编辑提供了一个贡献的机会。 在创建项目时，我想为开发人员和作家创建一个交流，合作和共享他们的知识的地方，以便我们可以创建任何人都可以理解的自述文件。

我们需要你，Feedmereadmes

Feedmereadmes的目标受众非常广泛：没有预算用于编辑服务的单个项目创建者和小型团队的组成。 Maintenanceer.io是一家新公司，可为希望为其开放源代码计划增添光彩和专业精神的公司提供类似的服务（还有更多其他功能，请检查一下）。 他们的创始人之一运行Awesome README列表 ，这是自述文件的宝贵资源。 他不久前将Feedmereadmes添加到列表中。

显然，Maintainer.io和Feedmereadmes之类的工作可以满足长期的需求。 要求在GitHub之前提供更好的文档，并且鉴于GitHub的高速发展（2000万个回购和计数），这种需求只会变得更加明显。

早在2010年，GitHub创始人Tom Preston-Warner在“ README Driven Development ”一文中仍然广受欢迎，仍旧有先见之明，以此为主题进行了报道，他主张首先编写README。 他写道：“首先，在编写任何代码，测试，行为，故事或任何东西之前，”。 “我知道，我知道，我们是程序员，该死的，而不是技术作家！但这就是您的错。编写自述文件对于编写优秀的软件绝对至关重要。在您撰写有关软件的文章之前，您根本不知道您将要编码的内容。”

多年后，文档仍然是许多人忽略的OSS开发的一部分。 结果：

• 自述文件没有基本的安装/运行/配置说明，给潜在的用户和贡献者带来不必要的麻烦。
• 没有说明项目背后的“为什么”和“如何”的自述文件-为什么存在，为什么与相似项目不同，创建者或其他人如何在生产中使用它，以及如何设计它。
• 自述文件太短或太混乱。

2017年2月，在听Rich Bowen在FOSDEM上演讲有关文档的脆弱性和失败时，我开始思考什么可以减少世界上文档生成的集体悲伤商机。 Rich的演讲标题为“阅读F *手册？也许您需要编写更好的f *手册”，重点是OSS项目创建者和维护者必须听取他们的听众并欢迎新手。 它鼓励听众“将整个项目社区视为其文档” –一个超越“开发人员不喜欢编写文档”刻板印象的想法（嘿， 很多作家都不喜欢写文档！）和“代码不言而喻”的神话。 “花点时间了解为什么人们问你这个愚蠢的问题，”里奇告诉FOSDEM人群。 “通常的问题是您的文档很糟糕或令人困惑。”

受到Rich演讲的激励，我后来在展厅里找到了他，以感谢他的启发。 当我们聊天时，出现了一个主意：为项目创建者提供免费的写作和编辑服务。 一小段步行路程和一个比利时华夫饼干过后，Feedmereadmes从GitHub的子宫中弹出，哭得很像婴儿，以解决其饥饿感。

Feedmereadmes的工作方式（以及针对谁）

对于项目创建者，第一步是通过“问题”功能链接项目的自述文件。 他们还可以将自己的README链接发布到@feedmereadmes ，我为他们创建了一个问题。

接下来，我编辑并校对自述文件。 在请求请求消息中，我问维护者一些问题，以帮助他们阐明项目目的。 如果不清楚他们为什么进行该项目，该项目如何工作以及该项目解决了什么（以及一些描述该项目如何解决实际问题的支持证据），那么我将这些问题与一些支持资源一起用于其他背景。 我在Zalando创建的Mozilla的Open Canvas ， 18f的开源指南以及README和产品分析模板就是我的典型选择。

当作家和编辑希望参与其中时，我只需将他们定向到问题跟踪器，并邀请他们要求一个项目来提供帮助。 我在此处创建的自述文件包含指向初学者的GitHub教程的链接。 我还简要介绍了免费工作背后的基本原理。 作为前新闻记者，博客作者和撰稿人，我对许多公司和实体提供“免费曝光”作为补偿这一事实非常敏感。 对于那些挣扎于靠手艺谋生的作家来说，“免费宣传”不会支付租金或印度食品。 考虑到这一点，我提供了以下说明：

[T]仔细思考为什么要贡献自己的写作和编辑技能，以使全世界的自述文件更具可读性。 可能是为了增加您对技术和开源的知识； 与有创造力的人合作； 帮助陷入困境的开发人员以您发现的简单方式改善他们的项目，但是他们可能会发现困难； 或建立具有不同工作前景的投资组合。 也许您被FOSS的自由交换和信息共享精神所吸引。 这些只是世界上许多人晚上和周末在计算机上度过夜晚，无偿工作的一些原因。

我还添加了一些建议，这些建议帮助我在工作中取得了更大成就：“去温暖的地方”。 换句话说，帮助那些欣赏你并让你觉得自己属于你的人。 如果项目创建者正在利用您或使您感到不舒服，请查找其他项目。 寻求可以让您感到受人尊敬，欣赏并成为其中一个的协作者。 不要满足于减少。

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

Feedmereadmes（严重的是，我是说真的）

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

对于需要README帮助的项目，也许我可以传递的最大教训是：为与文档有关的文稿做一个“ EZPass ”选项。 您可以通过允许贡献者分叉并修复您的自述文件来做到这一点。 想象一下，您是一位非常敏锐但还是新手的技术作家，他来您的项目时充满了编辑所有未大写的句子和拼写错误的单词的热情，但是看到了安装软件包的要求清单，并遵守旨在规避独裁和健谈机器人的规则。 该人可能会继续前进； 你刚刚让他们不知所措。

采用更多由README驱动的开发方法也将帮助项目创建者掌握文档创建的顶部，并可能增强总体项目可访问性。 代码并不总是代表自己。 经过一段时间后，它甚至甚至都没有和我们中的那些人说话，我们忘记了那一刻的灵感在想什么。 正如我的同事比尔·德·霍拉（Bill dehóra）所说：“文档化是一项高杠杆活动，使您可以专注于成果和想要实现的目标。文档化不但不会造成开销，还可以通过为用户和同事提供了解项目的背景而获得回报。是和为什么。”

即使您不同意我的同事Bill或Tom Preston-Warner，您仍然可以确保您的自述文件在您要使用它们的程度上易于使用。 我建议广义地定义“用户”，以包括您的同事，您的语言社区，您的经理，您的偶像，记者，赶时间的FOSS上瘾者以及您的父母。 （您希望您的父母为您感到骄傲，对吗？通过让他们了解您的工作来帮助他们。 告诉别人一个别人可以理解的故事 。）

结论

虽然“改善我的文档”可能仍然像开源开发的“放弃吸烟”或“每天奔走”，但我们的项目创建者（93％！）知道我们需要这样做。 但是我们中的许多人并没有将其作为优先事项。 嘿，很好，数百万GitHub的贡献者—当您准备就绪时， 我们将在这里 。

翻译自: https://opensource.com/open-organization/17/6/documentation-feedmereadmes-project

hbuilder自述文件