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