1. 金句:一页就要自洽
访谈说得很直:你得确保所有上下文都烘焙进这一页——如果一次只消费一页,而你假设用户已经先读过别的东西,AI 并不会先去读那另一样。
「见上文」「详见系列第三章」「前提条件见概念篇」对人是懒;对助手是陷阱。跨页前提等于没写——不是写在别的 URL 里就不算,是这次消费路径根本到不了那个 URL。作者以为系列读完才懂;到达层默认只给你这一页的机会。机会用完了,它不会自觉去补课,它会带着半截事实继续答。
烘焙,不是把百科全书塞进每一页。是把办完这件事所需的上下文写进这一页:适用谁、哪个版本、前置条件、关键限制、失败时看见什么、下一步去哪。小说伏笔可以跨章;帮助页不行。帮助页的读者——人和机器——常常从深链、搜索命中、工单粘贴进来,第一屏就是这一页,没有「上一章」可回。
国内帮助中心最常见的反例,是把「仅管理员可操作」「不可逆」「需先开通某某模块」写在系列总览或第三篇,任务页本身写得像人人都能点。人若从总览读起,也许能躲过;助手从任务页命中进来,等于没写。客户按半截步骤操作失败,锅很少记在「系列结构」头上,多半记在产品头上。
烘焙清单可以贴在写作规范首页:适用谁、哪个版本、前置条件、关键限制、失败时看见什么、下一步去哪。六项里缺一项,就还没资格说「这一页能办事」。清单不追求文采,追求一次消费自洽。
2. 静默截断:它可能没看见你后半页
有的消费路径对可见长度有上限,截断时有时完全不自知。危险操作、权限限制、不可逆警告写在文末,可能刚好被裁掉;助手仍自信作答。客户按半截步骤操作,客服再进线,你们才会发现「官方说明其实写了,只是它没吃到」。
「其实写了」救不了现场。现场只认这一次消费里出现过的字。把关键限制当成可选项往后放,就是在赌截断不会发生——这个赌,机器侧输面更大。
约三成团队已在让页面自包含——这是对截断现实的妥协,不是文风偏好。本篇不谈 Token 经济学,只谈烘焙:这一页要带齐办事所需。把关键限制挪到页前或页内醒目位置,不是排版洁癖,是对抗静默截断的土办法。国内现场里,长页后半截的「注意」常常最重要,也最容易在机器侧消失。
截断之外,还有「只取一页」:助手按检索命中打开单页,不会自动把你们的目录树读完。跨页「见概念篇」对它无效;「上文已说明」对它不存在。因此自包含与微内容、知识片段 是同一方向——块要小到吃得下,又完整到办得完。微,是消费单元的尺度;片段,是可检索、可引用的那一块事实。尺度对了,仍缺限制句,照样危险;限制句齐了,块却大到必被裁,照样危险。
再补一条现场观察:人分享链接时,很少附上「请先读系列前三章」。工单、群聊、邮件里飞的是单页 URL。自包含不是为机器发明的特殊文体,是对「单页到达」这一现实的承认。机器把这条现实放大了,并加上可能不自知的截断。
国内帮助中心还有一种「假自包含」:页很长,看起来什么都写了,关键限制却埋在折叠区、附录或「相关阅读」里。人对着长页也许会搜页内关键词;助手按块消费时,折叠与附录常常等于不存在。假自包含会给人「我们已经写全了」的安心,给机器「我没看见限制」的自信——两头都危险。
截断测试可以很粗:把页贴进任意有长度上限的摘要工具,看后半警告还在不在。不在,就往前挪。粗,但比开会争论「要不要自包含」更快出结果。
粗测试还有一版更贴近国内协作:把任务页链接丢进实施群,明确写「只准看这一页」。若同事追问「管理员权限在哪篇」,说明前提仍外包给了系列别处——对助手同样外包失败。人追问还能补课;助手常常直接带着半截上下文开工。
3. 人其实也从深链进来,自包含是双赢
分享链接、搜索命中、工单粘贴、实施群里的「看这个」,人同样常从中腰进入。页内写清适用版本、前提、下一步,人和机器一起受益。烘焙的是办事上下文,不是强迫每位读者读前言,更不是把每一页写成小百科。小百科是另一类浪费:把不办事的背景塞进任务页,既贵又容易把限制挤到后面。
能内容复用 的限制句,应嵌进相关任务页,而不是只活在某一章导读。一处维护、多页到达,自包含才不至于靠复制粘贴五份各漂各的——复制五份,第二周就会有三份过期。复用解决的是「同一限制写很多遍还各改各的」;自包含解决的是「这一次消费能不能办完」。两条线可以叠在一起,但本篇钉的是后者:页作为消费单元必须自洽。
国内自检可以粗暴有效:把任务页链接发给没读过系列的同事,只看这一页能否安全做完。缺的半句,补进页内;别补进「请先阅读系列总览」。再加一刀:把页后半的警告挪到步骤前或步骤旁,假装后半会被裁掉——人读起来也不吃亏,机器侧更不容易饿着答错。
自包含不是禁止互相链接。链接可以指向「下一步」「相关概念」「完整错误码表」;禁止的是把办完这件事的关键前提藏在必须先读的另一页里。链接是扩展,不是前提外包。
写作规范里可以加一句很硬的验收:若删掉站内其他所有页,只留这一页,读者(含助手)是否仍能判断「能不能做、怎么做、做错会怎样」。过不了,就还没烘焙完。邻近篇会谈更小单元与公共上下文;本篇只要求:这一次消费的页,先自洽。
硬验收还可以配一条软提醒:自包含不是禁止目录,也不是禁止系列。目录负责发现与治理;系列负责学习路径。两者都不能替代「单页到达时仍能安全办事」。把学习路径写成必须先读的前提,就是在和截断、深链现实作对。
4. Baklib:页是块,不是章回小说
Baklib 侧更稳的落点是:把页当成可发布、可检索、可深链的块,而不是章回小说的一回。章回小说鼓励伏笔;帮助与手册鼓励「打开就能办事」。树可以有层级,页不能靠层级偷懒。
帮助中心 与 产品操作手册 按任务与版本成页;少用「见上文」式写法。树负责治理与归类;页负责这一次消费。手册偏「这是什么、边界在哪」,帮助偏「此刻怎么做完」——边界事先划清,仍要求各自页内能办事,而不是互相「见对方第三章」。问答与总结若接上,也应从已发布块检索,而不是假设读者读过整本。
落地检查可以贴进写作规范:适用版本是否在页内;前置条件是否在步骤前;不可逆与权限是否可能被截断仍留在页尾;「见上文」是否能改成页内一句或可复用的限制块。过不了这些,先别急着加长系列——加长只会增加「假设别人先读过」的诱惑。
手册与帮助可以互相链,但不要互相绑架:帮助页不应默认读者刚读完手册第三章;手册页也不应默认读者已经在产品里点过一遍。各自页内带齐办事上下文,链接只负责扩展,不负责补前提。
一页就要自洽。假设别人先读过别的东西——人未必,机器更不会。烘焙进这一页,是把到达现实写进写作标准。标准立住了,截断仍可能发生,但至少危险事实更可能还在它吃得到的那一段里。自包含先站住,再谈写得漂亮。