为什么需要文档？ | Fumadocs 中文文档

人们经常问我，我们真的需要一个框架来构建文档站点吗？嗯，你不需要。

文档站点在软件开发中非常重要，公司内部开发者用来理解架构的内部文档，框架的文档， Web 标准的文档……

构建文档看似简单，但可能很困难。

构建文档有许多范式，但编写对初学者友好的文档可能很困难。结果，人们倾向于使用强大的文档框架，使文档站点互动且直观。

过度工程化

对于一个小库/API 服务的文档，你可能不需要设置一个 Next.js 站点并花费时间编写你的站点。在这种情况下，Nextra 或 Fumadocs 可能不如 GitHub wiki 和 Swagger 文档好。

它们提供良好、像样的 UI、基本功能，以及文档编写的适当工作流程。 DX 已经足够好，我想不到任何理由切换到全功能文档框架，只是为了让你的文档看起来华丽。

我只会推荐用 Markdown 编写你的文档，并在 GitHub 仓库中使其可访问。

现在你可能想知道，为什么主要服务和框架有自己的文档站点，使用文档框架构建？

当然，通常使用 GitHub Wiki 等工具就足够了，但并非总是如此。以组件库为例，你无法用 Markdown 展示你的组件。你会不断发现普通的 Markdown 文档缺乏能力和灵活性。

文档框架旨在解决这个问题，能够与主要库如 React.js 和 Vue.js 集成。好的例子是 Vitepress、Mintlify 和 Nextra - 它们使编写文档更方便有效，同时为读者提供更好、专属的体验。

对于任何超出简单库或 API 服务的项目，值得一试。

我绝不会推荐自己构建“自定义文档站点”，而不用合适的文档框架。尽管有 Don't re-invent the wheels 原则，你的手工文档站点实际上需要更多努力才能使其像样。

正确实现它们听起来就已经令人头疼了，对吧？

文档本身，肯定不是你的首要任务。你绝不应该花费宝贵时间重复造轮子 - 不值得。

从我的角度来看，我宁愿使用 GitHub Wiki，而不是重复造轮子。为什么不选择一个像样的解决方案呢？它能节省你不可或缺的时间，并帮助减少互联网上糟糕的文档站点。

我个人更重视阅读体验，而不是华丽的引人注目的 UI。你可能会注意到，我们没有到处使用动画，并且避免了许多华丽的设计。

UI 的华丽应该只留在登陆页面，文档站点应该专注于内容。导航元素是浏览站点的辅助工具，绝不应该占用屏幕太多空间。

我最讨厌的设计是 两个侧边栏，它混乱且无意义。你可以将所有项目组织到一个单一、干净的侧边栏中，但人们反而在导航栏中添加了两个汉堡按钮。

Next.js 文档

我最喜欢的文档站点仍然是 Linear 文档，看起来好且简单。