打开一个文档网站，文档网站你最该关心的文档网站不是设计多漂亮，而是文档网站搜索框能不能在三秒内把你带到正确的代码示例上。我见过太多团队花三个月搭出来的文档网站文档站，首页动画炫得让人眼花，文档网站结果用户找个API参数要翻五层菜单。文档网站这事挺荒诞的文档网站。
去年帮一个开源项目做文档迁移，文档网站原站点用某静态生成器搭的文档网站，侧边栏导航有七百多个条目。文档网站用户反馈最多的文档网站问题是“我知道答案在里面，但就是文档网站找不到”。我们统计了搜索关键词，文档网站前二十个里有十四个是文档网站直接搜函数名。这说明什么？文档网站文档站的核心功能就一个：让开发者用最短路径拿到他要的那段信息。其他都是装饰。
搜索不是功能，是入口
很多文档站把搜索框藏在右上角，图标小得跟蚂蚁似的。点开之后还只支持标题匹配，搜个useEffect返回一堆无关页面。理想状态是：搜索框默认聚焦，支持全文检索，结果按相关度排序，每条结果下面直接显示匹配到的代码片段。Algolia DocSearch 之所以被大量采用，就是因为它做到了这几点。我自己维护的一个小项目文档，换了搜索方案之后，用户平均停留时间从四分钟降到两分钟——别误会，这是好事，说明他们更快找到答案就走了。
有个细节值得说：搜索结果里高亮关键词不够，最好把上下文也带出来。比如搜“配置超时”，直接显示“在 config.yaml 中设置 timeout: 30s”这一行，用户扫一眼就知道对不对。这比让他点进三个页面去确认要友好得多。
导航结构暴露的是作者思维
侧边栏怎么分类，直接反映写文档的人有没有站在使用者角度想问题。我见过按代码模块分的，也见过按开发流程分的。哪种好？看场景。如果是SDK文档，按“安装→初始化→核心方法→进阶配置→错误处理”这条线走，新手能顺着爬。如果是内部系统文档，按业务域分更合理，因为查文档的人通常已经知道自己在哪个业务环节。
最怕的是那种“综合”“其他”“杂项”分类。一个条目被放进“其他”，基本等于宣告它永远不会被找到。我自己的做法是：如果一个条目找不到合适的分类，要么说明分类体系有问题，要么说明这个条目本身就不该单独存在，应该合并到某个已有页面里。
代码示例要能直接跑
文档里的代码块，最忌讳只写一半。比如展示一个函数调用，参数用...代替，用户复制下来还得自己猜要传什么。好的做法是给完整可运行的示例，哪怕长一点。GitHub 的文档在这方面做得不错，每个代码块右上角有复制按钮，复制出来的内容不带行号和多余缩进。
还有一个坑：代码块里的变量名要和正文解释保持一致。我见过正文说“传入 apiKey”，示例里写的是 token，读者直接懵掉。这种不一致比没有示例还糟糕。
版本切换别做成摆设
文档站带版本下拉框的不少，但很多切换之后只是换了个URL，内容根本没变。用户以为自己在看v2的文档，实际上还是v1的内容。这比没有版本切换更危险。真要支持多版本，要么每个版本独立构建，要么在内容层面做好条件渲染。偷懒的做法迟早会被用户发现，然后在issue里骂你。
我观察到一个现象：维护得好的文档站，通常把“当前版本”和“最新版本”的差异标注得很清楚。比如某个API在v3被废弃了，v2的文档页面上会挂一条醒目的提示，告诉用户替代方案是什么、从哪个版本开始生效。这种细节花不了多少时间，但能省掉用户大量试错成本。
说到底，文档网站是个工具，不是作品集。它的成功标准只有一个：用户能不能快速找到他要的东西，然后离开。任何增加这个路径摩擦的设计——不管看起来多酷——都应该被砍掉。