我们如何在Docusaurus上建立我们的文档

为了覆盖我们的基础，我们需要改进和扩大我们的文档，这一次，我们想用Docusaurus使其可扩展。

制作优秀的、用户友好的文档需要大量的时间、精力和资源。好的文档是工程师们开始使用产品并最终长期使用产品的基础，这使得它对用户的保留和增长都至关重要。因此，在Courier建立我们的文档是我们非常重视的一项任务。

我们最初是为一个非常小的、特定的受众创建文档的，他们对Courier有特定的用途。然而，随着时间的推移，我们的用户群、他们的使用案例以及我们的产品本身的增长，我们需要改进和扩大我们的文档，以覆盖我们的基础。这一次，我们想让它具有可扩展性，并专注于良好的用户体验。我们决定使用Docusaurus来做到这一点，这使得我们的工程师能够更有效地协作和更新我们的文档。下面是我们如何建立我们的文档，以及我们在这个过程中学到的可能对你有用的东西。

识别我们的文档流程中的挑战

当我们刚开始做Courier的时候，我们只是想让文档解释如何使用Courier这个产品。因此，我们找到了一个可以帮助我们的工具。ReadMe。

ReadMe给了我们足够的功能来开始我们的文档工作。我们可以在需要时不费吹灰之力地创建和更新我们的文档，但我们不能根据需要进行合作，而且一次只能保存一个草稿。这是一个重大的挑战，因为如果任何人在同一时间在同一个文件上工作，他们可以很容易地覆盖其他人的工作。ReadMe也有一个平面文件结构，使用起来很不方便。他们的CLI中也没有真正的Git集成，所以我们在文件版本和协作方面有问题。最终，这意味着文档在审批过程中会有不必要的时间，而且不是每个人都能在出现问题时提出改进建议。

因此，一些年来，在一些重要的产品更新之后，我们知道是时候进行一次重大的文档更新了。ReadMe很容易上手，在最初的几年里为我们提供了很好的服务，但我们需要一些东西来解决我们更具体的痛点。

文档工具的先决条件

我们知道我们需要新的东西。下一步是决定哪些解决方案是必要的，以解决我们下一个版本的文档的痛点。团队提出了一份关于我们未来将使用的文档工具的要求清单。

无限的合作

一个成长中的公司所面临的幸福挑战是，随着团队和产品的成长，几乎每个方面都需要扩展。随着Courier技术团队的壮大，我们有更多的主题专家为文档提供意见，这对文档的质量是个好消息。然而，更多的中小企业意味着我们需要更多的人能够在一个时间段内协作完成草案。由于我们的团队将继续增长，无限的协作是我们未来文档工具的基本需求之一。

版本管理

一个成长中的公司不可避免地会有一个成长中的产品。随着产品新版本的发布，总会有一个重叠期，即我们的一些用户在使用旧版本的产品，而一些用户在使用最新的版本。我们的文档需要满足这两组用户的需求，这意味着为了确保每个人都有正确的信息，版本划分是一个重要的文档功能。例如，我们需要将我们的API 1.0.0版本的文档与API 2.0.0版本的文档分开，并确保可以在不同的版本之间快速而方便地更新和切换。

这个版本也很重要，它允许选择将草稿与官方文档分开存储，这样团队就可以在没有突破性变化的压力下安心工作。

链接验证

对产品文档中的用户体验来说，最糟糕的事情之一是用户点击一个链接后得到一个404错误。这使得用户更难留在文档中并遵循指示，这最终会影响多少用户成功地开始使用产品和/或能够自己解决故障。一个包括内部链接验证的文档工具将在很大程度上避免破坏性错误和用户体验问题。

本地化

我们有来自世界各地不同民族的客户，他们说着各种各样的语言。为了迎合全球观众，用户需要能够阅读我们的文档并获得他们需要的帮助，无论他们说什么语言。将我们的文档本地化，如链接验证，可以提高用户保留率和用户体验。

Docusaurus与我们的名单相匹配

有了我们的清单，我们就可以开始研究，寻找合适的新工具。经过一些研究，我们发现建立在React上的Docusaurus允许无限的协作、版本控制、链接验证和本地化。

有了Docusaurus，我们把我们的文档建成了标记，并把它们导出为静态网站。我们创建了可重复使用的自定义组件，现在可以完全控制我们的文档构建方式。MDX集成也特别有用，因为它允许任何JavaScript代码被嵌入到.md文件中。

通过几行代码，我们可以调整我们的主题以适应我们的品牌颜色，或者通过摆动我们想要的组件来定制我们文档的任何部分。我们还可以使用插件来扩展我们从Docusaurus得到的功能。一个例子是我们的搜索功能的插件，允许客户找到相关的文档。

我还自己建立了我们的自定义API探索器，它使开发者能够直接从我们的文档中尝试我们的API方法。我把它建成了一个放置在MDX文件中的嵌入式React组件。因为我们在Vercel上托管我们的文档，所以我们可以利用Vercel函数来代理API Explorer的请求，通过我们的文档后台端点来代理Courier API。

有了Docusaurus，我们已经能够快速而轻松地建立我们的文档。现在，我们可以通过简单地克隆GitHub上的repo，从我们的主分支上分出，实施修改，并创建一个拉动请求（PR）来进行更新。一旦有人审查并批准了PR，它就会与主分支合并，然后部署到Vercel，并将更改内容更新到我们的网站。

我们只需要一个GitHub账户和一个集成开发环境（IDE）就能为我们的文档做出贡献。这有助于我们跟踪文档的每一个维护任务。