最近一项 GitHub 调查显示，超过 90% 的受访者表示，开源项目的首要问题之一是文档不完整或令人困惑。
我们能做些什么来改进它呢？
GitHub 用户认为文档质量差是 #opensource 项目的首要问题之一。我们如何改进它？https://#/t2Jmt9QDJc pic.twitter.com/d1GEPYT22P
— Alex Sanchez (@_alxsanchez) 2017 年 6 月 12 日
答案有几种不同程度的干预措施。
第一个也是最明显的措施是聘请专业人士来处理它。红帽 是一家拥有稳定作家团队的开源公司，而 NPMJS 正在招聘他们的第一位全职作家。 可以肯定地说，有很多作家在有资金支持的开源项目上工作。 这个解决方案很棒，作为一名技术作家，我完全赞成，但这既昂贵又困难。
另一方面，最低程度的干预措施是忽略这个问题。许多小型开源项目都使用这种方法，因为他们没有时间、精力、金钱或专业知识来做任何事情。 有些项目至少尝试为文档的 pull request 发放贴纸。
大多数项目都处于中间地带，没有足够的资金聘请技术作家，但他们有动力帮助用户使用产品。 这些项目可以做些什么？
降低门槛
首先，通过降低准入门槛，使贡献更容易。 以下是一些您可以尝试的低成本或零成本的方法。
- 使用模板来指导写作。
- 将文档放在可访问的开放格式中。
- 允许（并满足）关于文档的功能请求。
- 收集未附加到您项目的文档。
关于如何吸引程序员成为贡献者的文章和会议演讲有很多，关于代码贡献者的一切需求也适用于非代码贡献者。 然而，贡献文档有一种特殊的焦虑感，因为你知道人们会阅读这些文档，而不是他们可能永远不会激活的代码。 如果你不是核心项目团队的一员，你真的足够了解来编写文档吗？
有些项目声称只有专家才有资格编写关于该项目的文档，这是错误的。 任何人都可以准确地编写关于项目的文档，就像任何人都可以编写有用的代码一样，只要他们有良好的审查、来源和反馈。
文档模板
聘请作家或借鉴现有项目的风格指南来创建文档模板。 这是一个可填写的表格，贡献者可以使用它来创建有意义的主题或描述。 例如
_______ 命令告诉系统 ___________。 ______ 命令接受以下开关
_______ 设置文件名
_______ 开启日志记录
_______
相关命令有 _____, _______, 和 ________。
这是一个简短的模板，但允许人们跳过思考应该包含哪些内容的心理负担，真正降低了门槛，使他们更容易在编写代码时编写文档，或在事后贡献文档。 以这种方式标准化命令也将使您的项目更易于使用，因为用户可以扫描它们，每次都能找到可预测的信息。
有很多漂亮而强大的技术写作工具。 你不应该使用任何这些工具。 你应该使用尽可能小而简单的工具来编写和征集文档。 理想情况下，它应该是人们可以使用文本编辑器添加内容的工具，并且应该是自编译的 ，这样在贡献之后和发布之前就不会出现故障点。 不要将您的信息放入专有 Wiki：将其放入 HTML 或 Markdown，或一些其他熟悉的标准。 以后将其转换为更专业的文档会更容易。
文档请求
文档请求应与功能请求具有相同的路径和权重。 您需要有一种方法让人们告诉您他们失败的地方并向您寻求帮助。 如果您配置了聊天机器人，请确保它正在收集文档请求。 如果您配置了分析工具，请查看人们正在搜索但未找到的内容。 添加尽可能多的请求路径，然后您可以整理它们并进行简单的频率分析，以确定您的用户最沮丧的内容并努力修复它。
任何存在足够长时间的项目都有文档存在于项目本身以外的地方。 人们在 Stack Overflow 上互相提问，在 Youtube 上谷歌搜索答案，并在行业特定的邮件列表中互相询问。 无论您的用户在哪里互相帮助，您也应该阅读那些有用的文档，并在获得许可的情况下将其拉回到项目中。 图书馆邮件列表中的某人可能永远不会想到来您的编目软件贡献文档，但他们已经为他们的图书馆员同事写好了，这是很好的有用信息。
使文档更容易编写意味着更多人将为您创建文档。 这很明显，但很少有项目努力降低门槛。
增加奖励
当人们避免痛苦或寻求奖励时，他们会改变自己的行为。 我们不希望我们的项目中出现痛苦，所以我们可以努力使奖励成为行为改变更可能的原因。 以下是一些方法
- 使文档贡献与代码贡献同等重要。
- 奖励文档请求（可能包括审阅者职责）。
- 为非代码贡献者概述贡献者晋升路径。
如果您将文档、用户体验和可访问性视为不如代码重要，这将在您的项目中体现出来。 确保您的项目没有分为“有价值的编码人员”和“其他人，其中一些人编写文档”。 如果您为代码发放贴纸或 T 恤或挑战币，也为非代码贡献发放。 在一段时间内，这对您的社区来说将是如此令人惊讶，以至于您会看到许多新的、兴奋的贡献者。
感谢人们请求文档。 我特别喜欢奖励请求文档的人，让他们可以审查他们请求的东西！ 狡猾但有效。 有点像对待错误报告一样对待它：“有些东西使产品对我来说无法使用，我无法前进，除非你修复它。” 那件事可能是一个损坏的功能标志或过时的安装程序，但无论哪种方式，用户都倒霉了。
如果您的项目有从用户到请求者到贡献者到核心的晋升路径，请确保非代码贡献有同等的路径。 如果您希望有人自愿为您编写一流的文档，您需要表明您重视他们的时间和专业知识。
总结
编写代码与编写文档难度相当，只是技能组合不同。 正如 GitHub 调查显示的那样，虽然如此，但并没有很多人这样做，或者做得很好。 这是因为总的来说，开源项目并没有将可用性作为优先事项，无论是通过文档还是界面。
改变文档质量差或缺失的问题既容易（使用我上面概述的步骤），又非常困难。 这将是困难的，因为它呼吁我们作为一个运动开始关心与我们不同的人的体验，而这并不是开源传统上奖励我们的东西。 存在一种 内部笑话、旧习惯和社区欺凌的文化，我们很多人都在努力改变。 但改变是困难的，世界各地的新用户都在被纠正如何发音他们只读过的操作系统名称，即使他们确实设法安装了它。
考虑鼓励非代码贡献，以此让后来的用户感觉不那么想放弃并转向商业软件，因为开源软件太令人沮丧而无法使用。 我知道我尝试这样想。
4 条评论