对人好，并不等于对智能体好

文档站首页若只服务一种读者，过去十年大体够用。

人会扫目录、会搜关键词、会从「上一章」连着往下读。作者也习惯按教材写法：先概念、再架构、再逐步操作，中间来一句「如前所述」。排版舒服、截图清晰，评审就过了。

现在桌上坐着第二位读者。它不逛首页，不欣赏你们的插画，也不懂「如前所述」指向哪一段。它可能从编码助手里抽一截、从站内问答里检索三页、从某份公开 URL 里咬下一块——上下文窗口有限，长页还会被静默截断。行业公开调研里，已有三成左右团队在补显式上下文、让页面自包含，约四分之一在投结构化数据。有人把话说得很直：对人好的东西，不自动对智能体好；token 贵，上下文是公共品，智能体要的是能完成任务的、尽可能小的文档单元。

这不是让你抛弃人类读者。是承认：只优化「给人扫读」的那一套，AI-Ready 往往还没开始。把原站换个皮肤、加个对话框，底下仍是一部线性长篇，助手吃到的仍是半截、过期或互相打架的碎片。

两套读者，可以共用一棵树；不能假装一套写法打天下。

所谓微内容，就是短小、目标单一、能单独被检索和引用的内容块——一问一答、一条限制说明、一个配置项。它不是「少写一点偷懒」，而是给第二套读者准备一口能咽的粮。

换预算口吻也成立：再多请一个人把长文写得更漂亮，不如先把最高频的二十个任务拆成自包含页。漂亮长文仍然有用，但 AI-Ready 的第一笔钱，往往花在块与发布边界上，而不是花在换一套更炫的对话框皮肤上。

人的阅读像逛商场。

目录是楼层导视，长文是可以慢慢逛的店。他愿意先扫标题，再决定深挖哪一节；遇到不懂的词，会回头翻概念章。线性叙事对他是友好的——故事完整，负担在「我有没有耐心读完」。

Agent 的阅读更像急诊分诊。

它带着一个具体任务进来：重试策略怎么配、某个错误码什么意思、这个权限缺了会怎样。它需要的单元最好自己站得住：目标、前提、步骤、结果、相关链接，少依赖「请先读完系列前四篇」。一页写到八千字、截图二十张，对人或许是详实；对助手可能是窗口里被裁掉的后半截——裁掉的刚好是「危险操作」那几句。

国内现场里，冲突常常长这样。产品手册按「从零搭建」写成一章，客服收藏的是飞书里拆出来的三步口诀；站内问答若整章吞进去，总结时容易漏掉版本差异。另一边，FAQ 被很多人嫌「太碎、太老派」，对机器却意外友好：一问一答、边界清楚，检索命中后不容易串台。

这里用得上知识片段：把能单独成立的事实从长文里拆出来，人和助手都能按需取用，而不是强迫第二套读者从头读到尾。粒度会打架，这是真问题。切太碎，人维护不动；切太粗，机器用不起。AI-Ready 不是选边站，是故意设计双轨：给人的导航与综述还在，给任务与给检索的块也在，并且都从同一真源发布，而不是网盘里再藏一套「只给机器人看的说明书」。

周五市场改了产品名，官网换了；帮助中心长文第三节中间夹着旧名，站内助手检索命中该节，对外答出旧称呼。人扫目录时还能「凭感觉跳过过时段」；机器不会凭感觉，它只吃命中的块。块若不自洽，双轨就会在同一棵树上互相拆台。

不必一次上成「全网最懂你们的 Agent」。先把文档写成机器也不容易饿死的样子，几条就够用。

页面尽量自包含。打开这一页能办事；必须跨页时，用稳定链接指向现行版，少用「见上文」。关键限制、默认值、适用产品线写在正文里，别只活在作者的群聊记忆中。

任务与 FAQ 成块。一个常见任务一篇帮助；一个高发问题一条 FAQ。块可以组装进手册长文，但发布面上保留可单独检索的入口——人和助手都受惠。

少假定线性阅读。每一页都可能是「第一页」：搜索、分享、助手引用，都不会保证读者刚读过你的前言。开头用一两句交代这篇解决什么、不解决什么，比华丽的系列开场白更值钱。

结构化愿意投一点。元数据——给内容贴上的产品线、版本、适用对象等标签信息——能被系统带着走，比只丢一整本 PDF 更利于检索与总结。标题层级清楚，比堆一屏大段更利于机器定位。llms.txt 之类声明可以有，单独当银弹不可靠：它告诉爬虫「这儿有料」，长页照样会被截断；根子仍是块好不好、发没发布。

诚实边界也写进清单。站内 AI 智能搜索、对话问答，应是检索已发布内容再总结，而不是拿公网常识冒充你们的参数。人要点得回 Help/Docs 原文。MCP、编码助手读文档，是行业里越来越常见的通道——Baklib 主路径上先把已发布结构立住；不把「开箱即是你们的 Agent 网关」写成今天的交付。

国内现场还可以加一条很土的自检：把帮助中心某一长页发给同事，只让他看中间三分之一，问他能不能单独做完任务。人若做不完，助手被截断时也做不完。另一条：站内搜索你们最高频的五个任务句，前三条结果是不是现行、自包含的帮助页——若前三条是活动稿、旧菜单、内部代号，AI-Ready 还没开始，人机两套读者都会饿。

Baklib 侧，AI-Ready 更接近「怎么发布」，而不是「再买一个更会聊的模型」。

帮助中心 按任务与 FAQ 组织，文档站讲规格与概念，需要时再开开发文档 叶子——建设侧模板可点亮 Help、Docs、Chat、Developers 等门脸。知识仍在中台里审核、版本化；体验库只是不同门口。AI 问答吃的是已发布块，不是把整站糊成一团丢进提示词。

落地顺序通常是：先把树和块立住，再开对话。

分类、多级目录、多产品多版本先清晰；高流量任务拆成自包含帮助页与微内容块。然后才让 AI 客服 / 智能搜索接上已发布库：答得出时给总结，并尽量带回帮助中心或开发文档原文；答不出时承认，而不是编。作者继续对结构与终稿负责——模型会组词，组织仍要定哪一块算现行事实。急着先开对话框、后补块的团队，往往会在第二周发现：助手答得越溜，客服救火越忙。

对人好，仍然要做。目录、扫读、截图、可读性，一张都不能丢。只是到了助手也来读的年份，还得多做半步：让同一份知识，也能以小而自洽的单元被检索、被截断、被引用而不至于当场饿死。开发者文档里的错误码表、帮助中心里的任务卡、FAQ 里的边界句，往往比一篇「从入门到精通」更早被第二套读者咬到——先把这些块养干净，再谈更炫的对话体验。

AI-Ready 不是把原站抛光，是承认桌上坐着两套读者，并愿意为第二套读者改结构。结构改对了，人和机器吃的是同一棵树上的果子；结构没改，对话框只会更快地把半截长文说成权威。