想象一下，您刚刚加入一家新的科技公司，您被分配的首要任务之一是改进和集中组织面向开发者的文档。但有一个问题：这些文档存在于许多不同的地方、多个平台之上，并且在准确性、时效性和风格方面差异很大。
那么我们是如何应对这一挑战的呢？
了解范围
与任何项目一样，我们首先需要了解我们试图解决的问题的范围和界限。哪些文档是好的？哪些是有效的？哪些是无效的？有多少文档？文档是什么格式的？我们需要进行一次文档审计。幸运的是，Aneta Šteflová 最近在 OpenSource.com 上发表了一篇关于文档审计的文章，它提供了极好的指导。
接下来，对每一篇公开发布的文档都从其涵盖的主题、使用的媒介、时效性和质量进行了评估。一种模式迅速显现，不同的平台存在重大缺陷，这使我们能够以数据驱动的方式来停用我们现有的基于 Jekyll 的站点。审计还突显了我们的文档来源是多么分散——我们至少在七个站点上拥有面向开发者的文档。尽管搜索引擎可以很好地找到这些内容，但这种分散性使得 Mycroft（我们的主要受众）的开发者和用户难以浏览他们需要的信息。同样，这些数据帮助我们决定将文档集中到一个平台上。
选择中心平台
作为一个组织，我们希望限制使用的独立平台的数量。随着时间的推移，维护和更新多个平台以及集成接触点对于任何组织来说都会变得繁琐，但对于小型初创公司来说，情况会更加糟糕。
平台选择的另一个业务驱动因素是我们有两个主要但非常不同的受众。一方面，我们有高度技术性的开发者，我们期望他们会将文档推向极限——并且他们希望使用他们选择的工具——Git、GitHub 和 Markdown 来贡献技术文档。我们的第二个受众——最终用户——将主要消费技术文档，并且希望在一个吸引人的、受欢迎的平台上这样做，该平台在视觉上具有吸引力，并提供额外的功能，例如识别阅读时间和提供反馈的能力。从我们这边来看，捕获反馈的能力也是一个关键要求，因为如果没有关于文档质量的反馈，我们就没有坚实的基础来进行持续的质量改进。
我们能否找到一个能够满足所有这些相互竞争的需求的平台？
我们意识到两个平台可以满足我们所有的需求
- WordPress：我们现有的网站是基于 WordPress 构建的，并且我们内部拥有一些相当强大的 WordPress 技能。WordPress 的灵活性也满足了我们对阅读时间和捕获用户反馈等功能的要求。
- GitHub：几乎 Mycroft.AI 的所有源代码都可以在 GitHub 上找到，我们的开发团队每天都使用这个平台。
但是我们如何才能将两者结合起来呢？
使用 WordPress GitHub Sync 集成 WordPress 和 GitHub
幸运的是，我们的首席运营官 Nate Tomasi 发现了一个承诺集成两者的 WordPress 插件。
这个插件在我们的测试网站上进行了全面测试，并且顺利通过。它易于安装，配置简单，只需要一个 OAuth 令牌和 GitHub 的 Webhook，并提供 WordPress 和 GitHub 之间的双向集成。
然而，它确实有一个依赖项——Markdown——这被证明有点难以实现。我们试用了几个 Markdown 插件，但每个插件都有一些怪癖，会干扰非基于 Markdown 的内容的渲染。在经历了数天的挫败感，甚至尝试为我们的需求自定义编写插件之后，我们偶然发现了 Parsedown Party。当时非常兴奋！通过 WordPress GitHub Sync 和 Parsedown Party，我们集成了我们的两个关键平台。
现在是时候让我们的内容在视觉上对用户受众具有吸引力且可用了。
阅读时间和反馈
为了实现阅读时间和反馈功能，我们为 WordPress 构建了一个新的 页面模板，并在页面模板中利用了插件。
提前知道文章的估计阅读时间已被 证明可以提高内容的参与度，并为开发者和用户提供决定是现在阅读内容还是将其添加书签以供稍后阅读的能力。我们测试了几个用于阅读时间的 WordPress 插件，但最终选择了 Reading Time WP，因为它具有高度可配置性，并且可以轻松嵌入到 WordPress 页面模板中。我们将阅读时间放置在内容顶部的决定旨在让用户选择是现在阅读还是保存以供稍后阅读。在阅读时间到位后，我们随后将注意力转向收集用户对我们文档的反馈和评分。
有几个评分和反馈插件可用于 WordPress。我们需要一个可以轻松地为多种用例定制的插件，并且可以聚合或汇总评分。经过一些实验，我们选择了 Multi Rating Pro，因为它具有广泛的功能集，特别是能够在 WordPress 中创建一个评论评分页面——即，一个中心页面，工作人员可以在其中查看评分，而无需登录到 WordPress 后端。我们在这里遇到的唯一差距是设置评分选项显示顺序的能力——但这可能会在未来的版本中添加。
WordPress GitHub 集成插件还使我们能够链接回 GitHub 存储库，其中保存了原始 Markdown 内容，邀请技术开发者为改进我们的文档做出贡献。
更新现有文档
既然我们新的文档的“容器”已经开发完成，现在是时候更新现有内容了。由于我们的许多文档都是随着时间的推移有机增长的，因此没有风格指南来规范关键字和代码的样式。这是首先要解决的问题，以便可以将其应用于所有内容。您可以在 GitHub 上查看我们的内容风格指南。
作为更新的一部分，我们还进行了多次检查，以确保内容在技术上是准确的，并使用多张图片增强了现有文档，以提高可读性。
还有一些额外的工具使创建文档片段的内部链接变得更容易。首先，我们安装了 WP Anchor Header 插件。这个插件提供了一个虽小但重要的功能：使用 markdown-toc 库在 GitHub 中添加 id 内容，然后简单地复制到 WordPress 内容中，它们将自动链接到每个 <h1>、<h2>（等等）元素的 id 属性。这意味着内部锚点可以从 GitHub 中的 Markdown 内容中在命令行上使用 markdown-toc 库自动生成，然后简单地复制到 WordPress 内容中，它们将自动链接到 WP Anchor Header 生成的 id 属性。
接下来，我们将更新后的文档从 GitHub 导入到 WordPress 中，并确保我们拥有有意义且易于搜索的别名、描述和关键字——因为如果没人能找到，那么优秀的文档有什么用呢？！最后一项活动是实施重定向，以便访问旧文档的人将被带到新版本。
接下来是什么？
请花一点时间阅读我们的新文档。我们知道它并不完美——远非如此——但我们相信，我们已融入到我们新的文档基础设施中的机制将使其更容易识别差距——并快速解决这些差距。如果您想了解更多信息，或对我们的文档有任何建议，请通过 Chat (@kathy-mycroft) 或通过 电子邮件 联系 Kathy Reid。
经 Mycroft.ai 许可转载。
评论已关闭。