# General Translation Blog: 为人而写的文档设计
URL: https://generaltranslation.com/zh/blog/designing-docs-for-humans.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 在 AI 时代,设计为何依然重要,以及我们用来消除心智杂乱的文档设计原则。
Authors: Kevin Liu, Taylor Fang
Published: 2026-09-17
## 为什么要设计文档？
文档是网页设计中一个悬而未决的问题。各种模式与反模式随处可见，在现成模板中被无限复制。模板快捷省事，但风险在于把文档当成事后才考虑的附属品，而不是产品体验中需要针对具体用户去设计的核心部分。那些被普遍采用的方案也常常设计过度，堆砌视觉效果。我们认为文档站点需要**更简单、以内容为中心的阅读体验**，把更繁复的设计留给营销站点 (借鉴了 [Fumadocs 的作者](https://generaltranslation.com/blog/fuma-nama)的理念) 。
但在一个智能体已成为文档读者、同时也是文档创作者主体的世界里，**你还应该设计文档站点吗？**又何必在人类可读性和视觉设计上投入精力？
我们相信，在 AI 内容泛滥的时代，一个直观而有章法的文档界面反而愈发重要。这一信念源自我们对设计这门手艺的珍视，也源自我们对产品体验的执着。但它同样来自一个观察：**人类仍然在看、在读文档**。没错，智能体是代码的大规模执行者，但单看数量统计并不能说明一切。人们依然会浏览文档站点来理解和评估一款产品。而且人们越来越需要这样的界面：清理心智上的杂乱，把注意力引向真正重要的地方。
我们的文档改版完全从零开始，起点是[内容重写](https://generaltranslation.com/blog/rewriting-our-docs)中梳理出的几条并行用户旅程。文档的基本构件其实就那么几个：导航、搜索、控件、链接和内容。我们用更少的线条、更多的留白来编排它们，换来更清爽的视觉体验，并基于开源文档框架 [Fumadocs](https://generaltranslation.com/blog/fuma-nama) 构建，以获得最大程度的可组合性。
我们在写作上倾注了大量心血，也希望人们真的会去读。我们持之以恒的目标，是设计并维护一个让阅读体验流畅、甚至令人愉悦的文档站点。一路走来，我们沉淀出了一些核心设计原则。第一条，就是采用熟悉、易懂的界面。
## 直观的动线与方向
正如我们在介绍文档内容重构的博客中[所写](https://generaltranslation.com/en-US/blog/rewriting-our-docs)，文档帮助用户建立起对产品及其运作方式的心智模型。我们的设计也遵循同样的核心理念：有意为之且条理清晰的组织、逐层展开的复杂性与自定义能力，以及不打扰、甚至近乎隐形的细节处理。
屏幕的每个区域都**对应一类统一的操作或输出**，让各项功能出现在用户预期的位置。 (由于我们发现部分用户对视觉主题有强烈偏好，模式切换器在两个区域中都有出现。)
页面本身也构成一条直观的动线，**引导用户一步步抵达自己的目标**。
文档会突出显示用户可能想要采取的操作链接，例如前往 Changelog 查看更新、提问以获得支持，或预约产品演示。
## 清理心智杂乱
界面正变得越来越杂乱。诸如“眉标文字” (标题上方的引导小字) 、在多个方向上乱动的随机动画，以及多余的方框 (还都带着圆角) ，都是 AI 设计的典型痕迹。**视觉上的杂乱，必然带来心智上的杂乱。** 当每个 component 都只是为存在而存在，位置未经斟酌、与其他 component 也毫无关系时，意义也就消解了。
因此我们的首要任务是**削减心智杂乱**。这意味着删掉多余的 element；具体到我们这里，就是大量多余的线条、链接和按钮。
但它同时也意味着重整结构、重新组织，并做彻底的简化。其中尤为重要的是，我们把各个导航 surface 整合成一张地图，用来**组织并指向站点的心智概念**。
如今我们的侧边栏就是一个手风琴式结构，仅此一个。这听上去谈不上革命性，但在文档站点中已经很少见了——这类站点往往在多个位置、纵向横向地同时铺开好几条分区导航栏。
CI 会强制侧边栏保持清晰的 hierarchy，避免它沦为一长串同处一级、令人望而生畏的链接与 options。而且它是稳定的：点击某个链接不会把侧边栏的 options 整个换掉，也不会让你在返回时找不到原来的位置。
## 引导视线
清晰自然的浏览流程还能教会用户如何在界面中穿行。我们希望**通过强化视觉层级**，把用户的视线自然引向重要区域：导航、控件、内容和操作。
a) 在重要区域使用图标，打破大段文字的压迫感。
b) 在文本段落之间增加更多分隔符，以便对内容进行分组，让章节划分更加清晰。
c) 对文本采用差异化样式，包括使用斜体 (文档往往对此心存顾虑) ，并将正文字重降到 400。
受 [Linear 文档](https://linear.app/docs)的启发，我们尤其希望营造大量留白，让内容有呼吸的空间。Quickstarts 页面的改版很好地展示了这些原则的综合运用。
## 独具一格的 GT 气质
文档站点终归也是网页，不该显得毫无生气。我们一面小心把握分寸，避免过度设计喧宾夺主，一面也加入了一些「微 UI」细节，让文档融入 GT 的品牌美学与世界观。
我们为[标志性的 Fumadocs 目录组件](https://generaltranslation.com/en-US/blog/fuma-nama/#the-fumadocs-design-credo)设计了一处微妙的交互。它以 SVG 遮罩的形式支持服务器端渲染，层级缩进为 12px，还有一枚跟随指针移动的淡蓝色滑块。移动端抽屉则静态绘制相同的几何形状，因为触摸屏没有悬停状态。
侧边栏也用上了同样的遮罩。从上到下依次点开一个章节，蓝色滑块便会沿轨道滑动，在树状层级缩进处向内弯折，并逐行跟随指针。
其他 UI 基础元素也经过一番甄选，以消除 AI 式设计的通病。凡是承载含义的图标，一律使用实心风格；搜索、复制等控件则保留细描边字形。方框的圆角也更小。侧边栏、代码块和菜单的滚动条样式统一，不再是默认的原生与叠加层滚动条混搭。语言切换器则使用自定义的旗帜 SVG，而非旗帜表情符号，以保持哑光质感的视觉图形风格，并与落地页相呼应。
当然，我们的文档本地化体验也必须是顶级的：间距、对齐与顺序统统保持原样。
## 问题清单
在整个过程中，我们把注意到的各种反模式整理成了一份“问题清单”。
* 眉标文字
* 随意堆砌的多余说明文字
* 圆角过大的方框
* 非实心图标
* 与内容重要性脱节的间距变化
* 未本地化的文档 (！)
* 散落在页面各处的多组导航元素
* 似乎可以无限展开的侧边栏
* 一点击就变样的侧边栏
* 让人找不到当前位置的侧边栏
当然，我们仍在持续改进文档设计，也欢迎任何反馈。祝你设计文档愉快！
## Sitemap
See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.