2022年我们改进文档的6种方式

在Medusa，我们致力于为开发者提供最佳体验。文档在其中扮演着至关重要的角色，它能够指导开发者顺利使用软件。

作为 Medusa 的一名技术文档撰写人员，我深度参与了公司文档的开发，尤其是在内容撰写方面。2022 年全年，我们的文档团队不仅投入了更多资源用于文档建设，还积极探索各种改进方法。

在本文中，我将与大家分享我们在 Medusa 如何改进文档管理。

美杜莎是什么？

在深入探讨文档改进之前，了解 Medusa 是什么以及开发人员如何使用它非常重要。

Medusa是一个开源的可组合电商平台。它的架构由三个主要组件构成：

• 服务器：一个无头后端，负责处理与电商网站相关的所有业务逻辑和数据。它可以连接到任何前端，包括店铺页面和管理后台。
• 店铺页面：这是顾客浏览电商网站并完成购买的界面。我们提供基于 Next.js 和 Gatsby 的店铺页面模板，但开发者也可以通过连接店铺页面 REST API 来创建自己的店铺页面。
• 后台管理界面：商家可以通过此界面管理其电商网站的设置和数据。我们提供的 Medusa 后台管理界面具备所有必要和高级功能，但开发者也可以通过连接后台管理 REST API 创建自己的后台管理界面。

您可以在文档中了解更多关于 Medusa 的功能和架构的信息。

我们为什么决定改进文档

2022年初，我们的文档为开发者提供了运行Medusa所需的基本信息。虽然这些信息足以让他们入门，但不足以指导他们完成整个电商网站开发流程。

文档的内容、设计、收集的反馈等各方面都需要改进。为了实现这些改进，我们需要改变文档的处理方式，并投入更多资源用于文档开发。

我们如何改进文档

将文档视为产品

帮助我们实现所有改进的最关键改变在于我们管理文档的方式。在大多数软件公司，文档的优先级远低于软件本身，往往被视为事后才考虑的问题。

在 Medusa，我们很早就意识到，文档记录才是真正能够推动 Medusa 进一步普及的关键。

对于那些好奇的开发者来说，快速入门指南就足够了。然而，那些真正想用 Medusa 为自己或客户搭建电商网站的开发者，则需要文档来解释各种概念以及如何实现它们。

我们认识到文档也是一种产品，因此能够：

• 明确文档修改/新增内容的优先级。这些优先级可以根据公司目标、产品路线图、用户体验改进等因素来确定。
• 我们以周期性方式规划工作。现在我们使用Linear来管理文档周期、任务和待办事项。
• 让设计团队和其他团队参与进来，进一步改进我们的文档和我们提供的用户体验。
• 为了与核心工程团队保持更紧密的联系，我们需要确保文档的更新与产品变更同步进行。核心工程团队也使用 Linear，因此两个团队都能了解彼此的工作进展，从而保持工作同步。

重构了我们的 API 参考

我们之前的 API 文档需要进行重大改进，具体涉及以下方面：

• 持续维护，确保其中所有细节都能通过持续发布进行更新。
• 提供良好的用户体验，因为它运行缓慢且提供的信息很少。
• 提供如何使用和运行端点的示例。

为了改进它，我们决定对其进行彻底重构，包括它的生成方式和网站本身的构建方式。

API参考文档的 OpenAPI 规范现在会随每个新版本自动生成，确保其始终保持最新。我们还在代码（用于生成 API 参考文档）中添加了 OpenAPI 规范注释，其中包含使用 Medusa JS 客户端和 cURL 运行请求的示例。此外，我们还添加了预期请求或响应参数以及可能出现的错误示例。

该网站之前使用 Gatsby 和自定义主题构建。作为重构的一部分，我们将其更改为作为Docusaurus主文档的一部分运行，并使用Redocusaurus插件将其置于Redocly之上。

这使我们能够利用 Redocly 专为构建 API 参考文档而设计的功能和特性，从而进一步提升开发者的体验。

完全重新设计了文档

2022年最后一个季度，我们专注于重新设计文档，具体包括：

• 改善我们文档的用户和开发者体验。
• 重新设计首页，引导开发者了解 Medusa 中的基本概念和指南。
• 请提供符合我们品牌形象的设计。

多亏了我们的设计团队，我们才能推出简洁的设计，一个包含 Medusa 使用方法基本文档的精简主页，并改进文档中使用的现有组件。

收集用户反馈

开发任何产品（包括编写文档）的一个重要环节是确保用户能够真正从您所做的新增功能或更改中受益。我们通过不同的方式实现了这一点。

一种方法是在所有文档页面的末尾或某些步骤之后添加反馈组件，让开发人员告诉我们他们是否觉得内容有用，以及哪些方面可以改进。

这帮助我们发现了文档中我们遗漏的错误，或者发现了使文档更清晰的机会。

此外，我们还为每个代码块添加了一个报告按钮。这样，开发者就可以快速在 GitHub 上创建问题，并提供有关他们在使用该代码块时遇到的问题的信息。

导航栏中还提供了一个问题报告链接，开发者可以在浏览文档的任何时候使用该链接。这有助于我们快速排除问题和错误。

将 Vale 和 ESLint 集成到文档中

风格指南非常重要，因为它有助于在整个文档中保持一致的风格。文档编写方式的一致性至关重要，因为开发人员在浏览文档时会习惯这种风格。

然而，制定风格指南是一回事，真正应用并执行又是另一回事。作为人类，我们很容易忽略某些细节，尤其是在撰写内容时。开源项目尤其如此，因为有很多贡献者乐于助人，但他们可能并不了解如何遵循风格指南。

就像软件会编写集成测试或单元测试来确保软件中的更改不会破坏整个系统一样，我们使用Vale和ESLint为我们的文档样式指南实现了测试。

Vale 允许您为文档的文本内容定义一组规则。然后，当它对您的文档文件（例如 Markdown 文件）运行时，会根据您的规则显示内容中的任何错误。

ESLint 允许您检查 JavaScript 代码中的错误并强制执行编程风格。通过插件，它还可以与其他语言和格式集成。使用eslint-plugin-markdown 插件，我们能够检查文档中代码块的错误和不一致之处。

我们还把这两个工具集成到了我们的文档流程中，确保它们的测试在我们 GitHub 存储库中的每个文档拉取请求 (PR) 上都会运行。

运行用户试用

收集用户反馈固然重要。然而，为了提供良好的开发者体验，您还需要了解开发者实际如何使用您的文档。

最好的方法是观察他们在执行任务时如何使用该工具。为此，我们针对文档开展了用户测试。每个季度，我们都会围绕特定任务开展一次用户测试，并观察参与者如何完成该任务。

当你在文档中引入一项新功能并想了解开发者如何使用它时，这一点至关重要。这项功能真的好用吗？需要改进哪些方面才能使其更好？

这也是一项很好的练习，可以了解开发人员可能会遇到哪些问题，内容或信息架构可能会产生哪些误导，以及我们是否真正了解我们的文档用户。

如果您有兴趣帮助我们改进文档，请了解更多关于我们的用户试验以及如何成为参与者的信息。

接下来会发生什么？

撰写本文并不意味着我们拥有了最好的文档，改进文档的征程也远未结束。这是一个持续的过程，需要我们各个团队以及 Medusa 社区的共同协作。我们的目标是确保我们了解开发者的需求，并让他们能够轻松获取所需的信息。

您觉得我们改进后的文档怎么样？您还有其他改进建议吗？请在下方留言！

如果您对 Medusa 有任何疑问或问题，请随时通过Discord联系 Medusa 团队 。