为人而写的文档设计

为什么要设计文档？

文档是网页设计中一个悬而未决的问题。各种模式与反模式随处可见，在现成模板中被无限复制。模板快捷省事，却往往把某个具体应用的概念脉络硬塞进预制的模子里。这样做的风险在于：文档被当成事后再装点一番、塞进一个个方框的附属品，而不是被构建成用户理解产品的心智模型。

此外，那些被普遍采用的方案常常"设计过度"，视觉效果反而加重了阅读负担。我们认为文档站点需要更简单、以内容为中心的阅读体验，把更繁复的设计留给营销站点 (正如 Fumadocs 的作者所分享的那样) 。

但在一个智能体已成为文档读者 (同时也是文档创作者) 主体的世界里，**你究竟还有什么理由去设计文档站点？**还值得在人类可读性和视觉设计上投入精力吗？

我们相信，在 AI 内容泛滥的时代，一个直观而有章法的文档界面反而愈发重要。这一信念源自我们对设计这门手艺的珍视，也源自我们对产品体验的执着。但它同样来自一个观察：人类仍然在看、在读文档。没错，智能体是代码的大规模执行者，但单看数量统计并不能说明一切。人们依然会浏览文档站点来理解和评估一款产品。而且人们越来越需要这样的界面：清理心智上的杂乱，把注意力引向真正重要的地方。

我们的文档改版完全从零开始，起点是内容重写中梳理出的几条并行用户旅程。文档的基本构件其实就那么几个：导航、搜索、控件、链接和内容。我们用更少的线条、更多的留白来编排它们，换来更清爽的视觉体验，并基于开源文档框架 Fumadocs 构建，以获得最大程度的可组合性。

我们在写作上倾注了大量心血，也希望人们真的会去读。我们持之以恒的目标，是设计并维护一个让阅读体验流畅、甚至令人愉悦的文档站点。一路走来，我们沉淀出了一些核心设计原则。第一条，就是采用熟悉、易懂的界面。

页面结构图：Introduction 页面的线框图，四个区域以蓝色标出，并配有导航、链接、偏好设置、操作、主题开关、目录栏和内容卡片的真实截图，分别对应其所在位置

直观的动线与方向

正如我们在文档内容重写一文中所写，文档帮助用户建立起对产品及其运作方式的心智模型。我们的设计也遵循同样的核心理念：有意为之且条理清晰的组织、逐层展开的复杂性与自定义能力，以及不打扰、甚至近乎隐形的细节处理。

屏幕的每个区域都对应一类统一的操作或输出，让各项功能出现在用户预期的位置。 (由于我们发现部分用户对视觉主题有强烈偏好，模式切换器在两个区域中都有出现。)

全新文档的 Introduction 页面，勾勒出四个区域：左侧导航、右上操作、左下链接与偏好设置

页面本身也构成一条直观的动线，引导用户一步步抵达自己的目标。

在淡化的页面上标注的编号路径：定位、导航、阅读、选择、行动

文档会突出显示用户可能想要采取的操作链接，例如前往 Changelog 查看更新、提问以获得支持，或预约产品演示。

清理心智杂乱

界面正变得越来越杂乱。诸如“眉标文字” (标题上方的引导小字) 、在多个方向上乱动的随机动画，以及多余的方框 (还都带着圆角) ，都是 AI 设计的典型痕迹。视觉上的杂乱，必然带来心智上的杂乱。 当每个 component 都只是为存在而存在，位置未经斟酌、与其他 component 也毫无关系时，意义也就消解了。

因此我们的首要任务是削减心智杂乱。这意味着删掉多余的 element；具体到我们这里，就是大量多余的线条、链接和按钮。

旧版文档页面，被移除的元素以红色标出：搜索框、GitHub 横幅、侧边栏开关以及页头分隔线