文档加载状态_我们如何确定技术文档的状态？

文档加载状态

GitHub最近的一项调查中，超过90％的受访者表示，开源项目的主要问题之一是文档不完整或令人困惑。

我们该如何解决？

GitHub用户认为文档质量差是#opensource项目的主要问题之一。 我们该如何解决？ https://t.co/t2Jmt9QDJc pic.twitter.com/d1GEPYT22P

-Alex Sanchez（@_alxsanchez） 2017年6月12日

答案来自不同程度的干预。

首先也是最明显的是聘请专业人员来照顾它。 红帽是一家拥有稳定作家的开源公司， NPMJS正在招聘他们的第一位全职作家。 可以肯定地说，有很多作家在从事受资助的开源项目。 这个解决方案很棒，作为技术作家，我都赞成它，但是它既昂贵又困难。

另一方面，最低程度的干预却忽略了这个问题。 许多小型开源项目都使用这种方法，因为它们没有时间，精力，金钱或专业知识来做任何事情。 有些人至少尝试为文档请求请求提供标签。

大多数项目属于中间空间，那里没有足够的钱来聘请技术作家，但他们的动机是帮助用户使用该产品。 这些项目可以做什么？

较低的障碍

首先，通过降低准入门槛，使贡献更加容易。 这是您可以花很少钱或没有钱就可以尝试的一些方法。

• 使用模板指导写作。
• 将文档以易于访问的开放格式放置。
• 允许（并满足）功能文档要求。
• 捕获未附加到您的项目的文档。

关于诱使编码人员成为贡献者的文章和会议讨论有数十篇，关于代码贡献者需求的一切正确的观点也适用于非代码贡献者。 但是，与您可能永远不会激活的代码相反，在您知道人们会阅读的文档中存在一种特别的焦虑。 如果您不是核心项目团队的一员，您是否真的足够了解文档？

有些项目声称只有专家才有资格撰写该项目，这是错误的。 任何人都可以准确地撰写有关项目的信息，就像任何人都可以编写有用的代码一样，只要他们有良好的评论，资料和反馈。

文件范本

雇用作家或从现有项目中借用样式指南以创建文档模板。 这是可填写的表单，供贡献者用来创建有意义的主题或描述。 例如：

_______命令告诉系统__________。 ______命令进行以下切换：

• _______设置文件名

• _______打开日志记录

• _______

相关命令是_____，_______和________。

这是一个简短的模板，但是使人们可以省去思考应该包括哪些内容的思想负担，这实际上降低了障碍，并使他们在编写代码时更容易记录文档，或者事后编写文档。 通过这种方式标准化命令还可以使您的项目更加实用，因为用户可以每次扫描它们以查找可预测的信息。

有很多漂亮，功能强大的技术写作工具。 您不应该使用其中任何一个。 您应该使用尽可能小的和简单的内容来撰写和索取文档。 理想情况下，应该是人们可以使用文本编辑器添加的内容，并且应该是自编译的，这样在投稿之后和发布之前不会出现故障。 不要将您的信息放入专有的Wiki中：将其放入HTML或Markdown或其他熟悉的标准中。 以后将其转换为更专业的文档将更加容易。

文件要求

文档请求应与功能请求具有相同的路径和权重。 您需要有一种方法让人们告诉您他们失败的原因并寻求帮助。 如果您配置了一个聊天机器人，请确保它正在收集文档请求。 如果您配置了分析功能，则可以查看人们正在搜索什么而找不到。 添加您可以想到的尽可能多的请求路径，然后可以整理它们并进行简单的频率分析，以确定您的用户最受挫的地方并进行修复。

任何具有足够年龄的项目都具有除项目本身以外的文档。 人们在Stack Overflow上互相提问，在Youtube上搜寻答案，并在特定于行业的邮件列表上互相询问。 无论您的用户在哪里互相帮助，您都应该阅读该有用的文档，并在获得许可的情况下将其拉回到项目中。 图书馆邮件列表上的某个人可能永远不会想到使用您的编目软件来提供文档，但是他们已经为图书馆员们编写了它，这是非常有用的信息。

使文档变得更容易意味着更多的人将为您创建文档。 这是如此明显，但是很少有项目致力于降低障碍。

增加奖励

人们在避免痛苦或寻求奖励时会改变自己的行为。 我们不希望项目痛苦，因此我们可以努力使奖励成为行为改变的更可能原因。 以下是一些方法：

• 使文档贡献等于代码贡献。
• 奖励文件请求（可能要承担审阅人的职责）。
• 概述非代码贡献者的贡献者进度。

如果您认为文档，用户体验和可访问性不如代码重要，那么它将出现在您的项目中。 确保您没有将项目分为“有价值的程序员”和“其他人，其中一些人编写文档”。 如果您分发贴纸或T恤或向硬币挑战硬币，则也要为非代码贡献而分发它们。 在一段时间内，这会对您的社区造成极大的打击，以至于您会看到很多新的，激动人心的贡献者。

感谢人们索取文档。 我特别喜欢给他们奖励要求提供文档的奖励的想法，该文档可以使他们查看所要求的内容！ 鬼but但有效。 就像对待错误报告一样对待它：“有些东西使该产品对我不可用，在您修复它之前我无法继续前进。” 那可能是功能标记损坏或安装过程已过时，但是无论哪种方式，用户都不走运。

如果您的项目类型具有从用户到请求者，从贡献者 到 核心的进度，请确保存在用于非代码贡献的等效路径。 如果您想让某人自愿为您编写一流的文档，则需要证明您重视他们的时间和专业知识。

结语

编写代码并不比编写文档难，只是一种不同的技能。 但是，正如GitHub调查显示的那样，做得不好的人并不多。 这是因为一般而言，无论是通过文档还是通过界面，开源项目都没有将可用性作为优先事项。

使用上面概述的步骤来更改文档不良或丢失的问题既容易，又非常困难。 这将是困难的，因为它要求我们作为一种运动来开始关心与我们不同的人的经历，而这并不是开源传统上对我们的奖励。 开玩笑，老习惯和社区困扰的文化使我们许多人都在试图改变。 但是改变是困难的，并且即使他们确实设法安装了操作系统，世界各地的新用户也已经在如何发音他们刚刚读过的操作系统的名称方面得到了纠正。

考虑鼓励非代码的贡献，这是使您不太喜欢举手投奔商用软件的用户的方式，因为开源软件实在令人沮丧，无法使用。 我知道我会这样想。

翻译自: https://opensource.com/article/17/7/how-do-we-fix-technical-documentation-problem

文档加载状态