我们如何使用 Mintlify & Fern 构建开发者文档站点
我们如何使用 Mintlify & Fern 构建开发者文档站点
作者
Charlie Hopkins-Brinicombe
·May 15, 2025
如果你运营一家开发者工具公司，你就会知道文档有多么重要。事实上，你可以认为它比你的网站更重要。因此，在五月份，我们决定彻底改进我们的文档，以便为开发者创建更丰富的内容。我们的目标是让每一位访问文档站点的软件工程师都能快速了解 Trophy 的功能以及如何使用它。
以下是我们所做的决策以及做出这些决策的原因的简要概述，但如果你只想亲自查看，请访问 docs.trophy.so。
Trophy 开发者文档
选择文档提供商
文档即服务 (documentation-as-a-service) 领域似乎正在获得越来越多的发展势头。似乎在过去的几年里，创建和托管文档站点的方式比以往任何时候都多。
我们研究了几个不同的提供商，包括 GitBook, Docusaurus, Hashnode, Fern 和 Mintlify。 决策涉及各种因素，但总而言之，虽然我们使用 Fern 管理我们的 SDK，但我们选择 Mintlify 作为文档，因为它具有最佳的编写体验，支持自定义 React 组件，并且在自定义域名上托管更经济实惠。 Fern 和 Mintlify 都从 SDK 和文档站点的同一单一来源提取数据：Trophy 的 OpenAPI spec。
如果你正在构建 API 或 SDK 文档，我们 强烈 建议坚持使用 OpenAPI，而不是像 Fern definition 这样的平台特定规范。 这是因为基本上每个文档即服务提供商都支持 OpenAPI spec，因此如果你使用它，那么如果你对当前的提供商不满意，或者市场上出现一个更具吸引力的产品，则可以轻松地更换提供商。 在将我们的 API 文档从 Fern 迁移到 Mintlify 时，我们利用了这种可选性。
确定最佳导航方案
在为我们的文档选择导航策略时，我们考虑了以下几点：
- 尽可能以最少的点击次数显示最重要的概念。
- 使我们的 GitHub 仓库和状态页面等重要资源易于访问。
- 明确划分我们的平台文档、API 参考、教程和示例。
- 使开发人员在需要时能够轻松获得帮助。
我们尝试了多种方法，但最终决定采用选项卡式布局。
0:00 /0:08 1× Tabbed layout
- Home 选项卡是默认选项卡，旨在回答关于 Trophy 的功能以及开发人员为什么要使用它们的“是什么”和“为什么”的问题。
- Guides 选项卡旨在回答“如何”的问题。 一旦你决定要构建什么，此选项卡将为开发人员提供实际示例，并展示实施的最佳实践。
- API Reference 选项卡是开发人员探索 Trophy 提供的所有功能的游乐场。 它非常适合在开始编写代码之前测试想法，或者查找文档其余部分未涵盖的有关特定端点的特定详细信息。
每个选项卡中都有一些关键链接指向重要资源，例如我们的 GitHub，用于了解有关我们的 SDK 的更多信息，以及我们的 status page。 如果需要，还有一个快速的“mailto”链接可以联系支持人员，并且文档中每个页面的末尾都有一个支持部分。
0:00 /0:03 1× Quick links
创建更丰富的内容
流程图
一张图片胜过千言万语，文档也是如此。 在我们认为特别重要的是要清楚地传达核心概念的领域，我们添加了 Mermaid 图表，以帮助说明问题。
代码片段
如果没有代码片段，任何文档站点都不完整，但我们通过在每种我们支持的编程语言中包含代码片段，使你能够非常轻松地获得与你的技术栈最相关的代码片段。
许多代码片段还有助于突出显示文章中讨论的相关代码部分：
获得反馈
彻底改进的一部分是构建开发人员告诉我们他们对每个页面的看法以及提出改进或添加建议的方式。 由于我们的文档是 open source 的，因此任何人都可以非常轻松地直接在 GitHub 中建议编辑或提出问题。
0:00 /0:06 1× Collecting feedback
我们的文档路线图
为了使我们的文档对开发人员更好，仍然有很多工作要做，例如：
- 使每个页面都具有用户意识。 如果开发人员已经登录到他们的 Trophy 帐户，那么我们很乐意向他们展示已填写 API 密钥和首选编程语言的代码段和示例，就像 Stripe 所做的那样。
- 添加对其他语言的支持，以使我们的文档更容易为非母语英语人士所访问。
- 将 LLM 集成到我们的文档中，这样你就可以提出问题并比自己搜索更快地获得相关答案。
总结
更新我们的文档的过程大约花费了一个星期，我们对结果感到非常满意。 如果你有任何希望看到的内容或对设置自己的文档站点有任何疑问，请随时与我们联系。