文档是产品的第二张脸：vibe 项目的开发者文档写作实战

先划清边界，免得你读错篇。这篇不讲流量：搜索引擎和 AI 发现层的打法在《vibe-project-seo-aeo-guide》（SEO/AEO 实战）里，那是“怎么被找到”，本篇是“被找到之后拿什么留住人”。这篇也不讲给 agent 看的手册：《agents-md-project-manual-guide》讲的是 AGENTS.md——写给编码 agent 的项目说明书；更不讲需求文档：PRD 的写法去看《writing-prd-for-ai-agents》。本篇只讲一件事：给人看的开发者文档怎么写——从 Quickstart 到 API 参考，从 docs-as-code 的纪律，到 llms.txt 到底值不值得做的诚实评估。

一、文档决定转化：它是产品的第二张脸

开发者发现一个新工具的行为路径几乎是固定的：落地页扫一眼 → 点进文档 → 决定要不要试。绝大多数 vibe 项目死在第二步。不是产品不行，是文档首页 30 秒内没回答三个问题：这东西能干什么、我三分钟能不能跑起来、出了问题找谁。

大公司可以靠品牌和销售兜底，文档烂一点也有人用。一人团队没有这个奢侈。你的文档就是你的销售、你的客服、你的布道师，而且 7×24 小时不睡觉。把文档当成“写完代码顺手补的附属品”，等于把获客漏斗最关键的一环交给了运气。

换个角度想：vibe coding 让写代码变便宜了，代码不再是稀缺品。当人人都能一夜之间做出一个能跑的 demo，稀缺品变成了信任——而文档是建立信任最便宜的方式。一个 Quickstart 写得干净利落的项目，天然让人觉得“作者靠谱，代码也不会太离谱”。反过来，文档里到处是 404 和过期截图，用户会直接推断：代码也一样没人管。

所以本篇的立场很明确：文档不是成本中心，是转化漏斗的第二步，紧接在落地页之后。预算（你的时间）应该按这个优先级花。

先看三种最常见的烂文档，对号入座——vibe 项目里几乎都能见到：

• “自传体”文档：首页洋洋洒洒讲作者为什么做这个项目、心路历程、技术选型纠结。读者不关心你的心路历程，他关心他的问题能不能解决。把自传移到博客去，文档首页只留“这是什么、怎么跑起来”。
• “考古体”文档：Quickstart 里的命令是三个月前的，参数名早就改了；截图还是 v0.3 的界面，实际已经 v1.2。这种文档的杀伤力前面说过：它让读者浪费半小时，然后得出“作者不靠谱”的结论。考古体的根因永远是“文档没进仓库”，见第五节。
• “说明书体”文档：把每个配置项、每个参数平铺直叙列出来，没有场景、没有先后、没有“你通常只需要改这三个”。说明书体的问题不是信息少，是信息没有组织——读者要的是“带我走一遍”，不是“词典”。

这三种有一个共同点：都是站在作者视角写的。检验标准永远是读者视角：第一次来的陌生人，能不能在不认识你的情况下把东西跑起来。

二、先写 Quickstart：倒金字塔与“五分钟验收”

文档写作最大的误区是按“作者的逻辑”组织：先讲背景、再讲架构、最后讲怎么用。读者是按“自己的问题”来的，他只关心一件事：我能不能快速跑起来，看看这玩意儿是不是我要的。

所以文档结构应该是倒金字塔：最重要的放最前。首页第一屏就应该是三行安装命令加一个跑通的截图（或终端输出）。背景、设计哲学、架构图——这些重要，但属于“读者已经决定要用之后”才看的东西，统统往后放。

Quickstart 的验收标准只有一个，而且很残酷：找一个从没见过你项目的人，5 分钟内跑通 Hello World。做不到，重写。别找借口说“我的项目比较复杂”——复杂恰恰是更需要好 Quickstart 的理由。Stripe 的文档为什么被全行业抄？因为它的 Quickstart 真的能在几分钟内让你发出第一笔测试支付。

一个合格的 Quickstart 有三个硬性要素：

• 前置条件精确到版本。“需要 Node.js”是不合格的，“需要 Node.js 20+（推荐 22 LTS）”才合格。vibe 项目最常见的 Quickstart 翻车就是环境假设：作者本地是 Python 3.12，读者是 3.9，复制命令直接报错走人。
• 命令复制粘贴就能跑。每一行命令都应该是完整的、可复制的，不要出现“把 <your-key> 换成你的 key”这种半成品——至少给一个能跑通的示例值，并明确标出哪里要换。命令之间不要有隐含步骤（“先 cd 到项目目录”这种话如果省略了，新手会直接卡死）。
• 告诉读者“成功长什么样”。跑完命令，终端应该输出什么？浏览器应该打开什么页面？把预期输出贴出来。读者对照不上输出时，他分不清是自己错了还是文档错了——而他大概率会认定是你的错。

反面案例：首页放架构图。很多技术作者忍不住先展示系统设计的精妙——六个微服务的调用链画得漂漂亮亮。但第一次访问的读者连“这东西解决什么问题”都还没搞清楚，架构图对他就是噪音。记住顺序：先让他跑起来，再让他理解；先给他鱼，再讲渔。

看一个 Quickstart 改写的前后对比，就能体会差别：

改写前（作者视角）：“本项目是一个基于插件化架构的 Markdown 笔记应用，支持多种存储后端。在开始之前，请确保你理解了我们的设计理念（链接：设计哲学），并根据你的操作系统选择合适的安装方式……”——读者读了三段，还没见到一行命令。

改写后（读者视角）：

# 1. 安装（需要 Node.js 20+）
npm install -g moonote

# 2. 启动（浏览器打开 http://localhost:3000）
moonote start

# 看到 "Moonote running at http://localhost:3000" 即成功。
# 第一次用？跟着 5 分钟教程走一遍：[链接]

三行命令，加一句“成功长什么样”，加一个教程入口。设计哲学、插件架构、存储后端——这些等读者跑起来、产生兴趣之后再讲。Quickstart 的每一行都要回答“读者现在要做什么”，而不是“作者想说什么”。

三、Divio 四象限：文档混乱的根因是文体混写

Quickstart 写完，接下来的大坑是：文档越写越多，越写越乱。根因通常不是写得少，而是四种文体混在了一起。Divio 的文档体系（documentation.divio.com）把文档分成四个象限，两个轴：面向学习还是面向工作、偏理论还是偏实践：

图：Divio 文档四象限。横轴是“面向学习 vs 面向工作”，纵轴是“理论 vs 实践”。

• 教程（Tutorial，学习 × 实践）：手把手带读者做完一件事，读者学的是“怎么做这类事”。语气是“跟着我做”。比如“跟着本教程搭建你的第一个 xxx 应用”。教程允许啰嗦，因为目标是学习。
• 操作指南（How-to，工作 × 实践）：解决一个具体问题，假设读者已经知道自己要什么。语气是“要做 X，按这几步”。比如“如何为 API 开启鉴权”。指南要短、要直接，不要解释原理。
• 参考（Reference，工作 × 理论）：描述“是什么”，供查阅。API 端点参数表、配置项清单、错误码表都属于这里。参考文档的特点是结构稳定、可预测——读者是来“查”的，不是来“读”的。
• 概念解释（Explanation，学习 × 理论）：回答“为什么”。架构为什么这样设计、这个抽象解决了什么问题。解释性文档是建立深度信任的地方，但只能给已经入门的读者看。

混写的典型症状：在教程里解释原理（读者只想跑起来，你跟他讲设计哲学）、在参考文档里写教程（参数表里塞了五段“最佳实践”）、在操作指南里从头科普（“如何配置 HTTPS”开头先讲三页 TLS 历史）。每一种混写都在增加读者的认知负荷。

实操建议：给四种文体各一个固定的目录位置，比如 /tutorials、/how-to、/reference、/concepts。写新文档前先问自己：读者带着什么问题来？“我想学会”→教程；“我想解决 X”→操作指南；“我想查 Y 的定义”→参考；“我想知道为什么”→概念解释。分不清就说明这篇文档想讲两件事——拆成两篇。

四、API 参考的写法：机器生成，人工只写故事

API 参考是 vibe 项目文档里最容易“看起来很努力、实际没人能用”的部分。作者花两周手写了每个端点的中文说明，结果参数名和代码对不上——因为手写的东西一定会过期。API 参考的第一原则：能生成的就不要手写。

如果你用 OpenAPI/Swagger 定义接口，参考页就应该从 spec 自动生成（Redoc、Scalar、Stoplight Elements 都是现成方案）。代码变了，spec 跟着变，文档跟着变——这条链路不断，参考页就永远是对的。人工的精力应该花在机器生成不了的地方：操作指南和概念解释，也就是“什么时候用这个端点”“这个设计背后的取舍”。

无论自动生成还是手写，每个端点必须有三样东西：

• 一个可复制的 curl 示例。不要只给参数表，要给一个真实能跑的请求。开发者评估 API 的速度是：复制 curl → 跑 → 看返回。这个循环越短，转化率越高。示例里的鉴权头、Content-Type 都要写全，别让读者猜。
• 错误码表，而且要写“怎么修”。“400 Bad Request”这种描述等于没写。要写成：400（缺少必填字段 email）→ 检查请求体；401（token 过期）→ 重新走 /auth/refresh；429（超限）→ 看响应头的 Retry-After。错误码表的价值不在“列出”，在“给出下一步”。
• 版本标注。每个端点标清楚从哪个版本开始可用、哪个版本废弃。vibe 项目迭代快，废弃不标注等于给未来的自己埋雷。废弃端点要给迁移路径，不要只写 deprecated 就完事。

一个判断 API 文档是否合格的土办法：关掉你的记忆，只看文档，能不能在不读源码的情况下调通核心流程？如果作者本人都做不到，就别指望陌生人做到。

五、docs-as-code：文档进仓库的纪律

文档最大的敌人不是写得烂，是过期。过期的文档比没有文档更伤信任：没有文档，读者知道要去问；过期文档让读者按错误指引浪费半小时，然后对你的项目彻底失去信心。

docs-as-code 的核心就三条纪律，vibe 项目完全照搬得起：

• 文档进仓库。Markdown 文件和代码放在同一个仓库， docs 目录和 src 目录平级。好处是版本天然同步：切到 v2.1 的 tag，看到的就是 v2.1 的文档。文档放在第三方 wiki 或 Notion 里，三个月后一定和代码脱节——因为改代码的人想不起来去另一个系统改文档。
• 文档变更走 PR，一起评审。功能 PR 必须附带文档更新，否则不合入。这条规则一开始会觉得重，但它是唯一能长期保证“代码和文档同生共死”的机制。评审文档的标准很简单：按文档能不能把功能跑通。
• CI 检查死链。用 lychee 这类工具在 CI 里跑一遍全站链接检查，死链直接让构建变红。vibe 项目文档里最多的过期，就是指向旧版本、旧仓库名的链接——机器检查比人工靠谱得多。

Google 的开发者文档风格指南（developers.google.com/style）值得通读一遍，不是因为它权威，而是因为它把“怎么写清楚”拆成了可执行的规则：用主动语态、第二人称写步骤；一个步骤只做一件事；先给命令再解释。vibe 作者不需要全背，记住一条就行：文档是写给别人看的操作手册，不是写给自己看的学习笔记——学习笔记可以意识流，操作手册不行。

六、给 Agent 读的文档：llms.txt 的诚实评估

2024 年 9 月，Jeremy Howard 在 llmstxt.org 提出了一个社区提案：llms.txt。想法很简单：在网站根目录放一个 /llms.txt 文件，用 Markdown 列出网站最重要的页面和一句话摘要，再配一个 /llms-full.txt 放完整内容。Agent 来抓取时，不用在 HTML 汤里游泳，直接读结构化的 Markdown。

提案之后确实有人跟进。Simon Willison 做了 docs-for-llms 的实验，还写了 llm-docs 插件；2026 年他又记录了一个案例：Claude 实际读取了某站点的 llms.txt，并基于它生成了可用的文档链接。也就是说，至少在某些 agent 工作流里，这东西真的被读了。

但有三句诚实的话必须说在前面：

• 它是社区提案，不是正式标准。没有 RFC，没有 W3C 背书，只是一个被部分人采纳的约定。写进你的技术规划时，别把它当成和 robots.txt 同等地位的东西。
• Google 明确表示搜索不用它。它既不是排名信号，也不是爬虫指令。指望靠 llms.txt 提升 SEO 的，可以死心了。
• 实际被读取的频率很低。prosopo.io 在 2026 年 10 月公布了 12 天的访问日志：robots.txt 被请求了 511 次，llms.txt 只有 3 次。Agent 生态还在早期，读这个文件的 agent 是极少数。

结论：值得做，但别当流量渠道。成本就是一个下午：写一个 Markdown 文件，列出你的 Quickstart、核心概念页、API 参考的入口，每个配一句话摘要；再生成一个 llms-full.txt 把重要页面拼起来。把它当成“给未来 agent 的友好姿态”，而不是“获客手段”。心态对了，这事就值得做；心态错了（指望它带来流量），你会失望。

写 llms.txt 的实操要点：只放最重要的 10-20 个页面，不要把全站 sitemap 倒进去（那叫 llms-full.txt 干的事）；每个条目一句话说清“这个页面解决什么问题”，不要写营销话术；每次发版顺手更新——和 docs-as-code 同一条纪律。

一个最小可用的 llms.txt 长这样，照着改就行：

# Moonote

> 5 分钟上手的 Markdown 笔记应用，本地优先，支持插件。

## 快速开始
- [安装与首次启动](https://moonote.dev/quickstart): 三行命令跑起来，含成功输出对照
- [5 分钟教程](https://moonote.dev/tutorials/first-note): 建你的第一条笔记

## 核心概念
- [插件架构](https://moonote.dev/concepts/plugins): 为什么插件只能访问受限 API

## API 参考
- [REST API 总览](https://moonote.dev/reference/api): 端点、鉴权、错误码表

## 完整文档
- 全量内容见 https://moonote.dev/llms-full.txt（单文件，约 80KB）

注意三点：标题行用 # 写产品名；> 引用块一句话讲清产品是干什么的（agent 靠这句判断要不要继续读）；每个链接配“解决什么问题”而不是“页面标题复读”。llms-full.txt 就是把上面这些页面按顺序拼成一个 Markdown，方便一次喂给 agent 的上下文窗口。

七、导航即文档：别让读者在你的文档里迷路

内容写好了，还有一半功夫在导航上。vibe 项目文档最常见的导航灾难是：只有一个按作者写作顺序排列的侧边栏，新读者从上往下读，读到第三篇发现跟自己没关系——然后关掉。

侧边栏应该按读者旅程组织，而不是按写作顺序。实用的分组是：“开始用”（Quickstart + 安装 + 第一个教程）→“解决具体问题”（操作指南，按任务分组）→“查资料”（API 参考 + 配置项）→“理解设计”（概念解释）。这正好对应 Divio 的四个象限——信息架构和方法论是同一件事。

另外三个导航细节，成本都很低但效果明显：

• 站内搜索是刚需，不是加分项。文档超过 20 页，读者就不会再用侧边栏找东西了。Algolia DocSearch 对开源项目免费，接入一下午。没有搜索的文档站，等于没有索引的书。
• 版本切换器。v1 和 v2 的 API 不一样时，读者必须能一键切换文档版本。前面说过文档进仓库天然带版本，但前端得有个看得见的切换入口，不然读者永远不知道自己看的是不是当前版。
• 每页底部放“这篇帮到你了吗”或“发现错误？提 PR”链接。文档的反馈回路越短，腐烂得越慢。“被问两次进 FAQ”那条铁律，靠的就是这个回路。

导航做得好，读者会觉得你的文档“好找”；导航做得烂，内容再好他也找不到——效果等同于没有内容。

八、文档的度量：怎么知道写得好不好

文档最难的是没有反馈——代码有测试，文档没有。所以要主动装三个“仪表盘”，都不需要复杂工具：

• 看搜索词。文档站的站内搜索记录是最诚实的用户调研：如果大量人搜“鉴权失败”，说明鉴权那节写得不清楚，或者入口太深。每月花 20 分钟看一次搜索词 Top 20，排前面的就是文档的洞。
• 给文档 issue 打标签。GitHub issue 里凡是因为“文档没写清/写错了”来的，打上 docs 标签。每季度数一数：如果 docs 标签的 issue 占比在涨，说明文档在腐烂；如果某个页面反复被问，说明那页要重写。这就是“被问两次进 FAQ”的量化版。
• Quickstart 的“跑通率”抽查。每季度找一个没用过你项目的人（朋友、群友都行），看着他从零跑 Quickstart，记录卡住的地方。作者自己永远测不出 Quickstart 的问题——因为作者知道所有隐含步骤。这是最便宜的可用性测试，一年做两次就够。

这三个度量都不需要你成为数据分析师，它们的作用只有一个：把“文档好不好”从感觉变成证据，让你知道下一版文档该改哪里。

九、文档的国际化：英文版什么时候值得做

vibe 项目一旦在 Product Hunt、Hacker News 或 X 上露过脸，英文读者就会来。要不要做英文文档，取决于你的获客渠道：如果流量的 30% 以上来自英语世界，英文文档就不是可选项。看一眼访问统计就知道，别凭感觉。

国际化的实操路线，分三档，按投入排序：

• 第一档：Quickstart 双语。只翻译 Quickstart 和安装页，其他保持中文。这是投入产出比最高的一档——英文读者能跑起来，深入使用时再用翻译工具啃中文文档。很多独立项目长期停在这一档，完全够用。
• 第二档：核心路径双语。Quickstart + 常用操作指南 + API 参考（API 参考本来就英文为主，翻译成本低）。概念解释和教程可以先放一放。
• 第三档：全站双语。只有当你明确在做海外市场、且有持续维护的精力时才上。全站双语最大的坑不是翻译，是同步：中文改了，英文没改，双语就变成了双倍的过期文档。

翻译质量上，机器翻译 + 人工校对是 vibe 团队的现实选择。但有一条红线：代码示例、命令、参数名永远不要翻译。只翻译解释性文字。把 moonote start 翻成中文的文档，见一个笑话一个——但这种笑话真的存在。

目录结构上，推荐按语言分目录（/docs/zh/...、/docs/en/...），而不是中英混在一个文件里。混排的文件维护起来是噩梦，PR 评审时也分不清改的是哪种语言。

十、维护节奏：文档是活的，发布 checklist 收尾

文档写完不是结束，是维护的开始。vibe 项目最常见的死亡曲线是：发布时文档光鲜，三个版本后文档和代码各说各话。防止腐烂不需要复杂的流程，只需要两条节奏：

• 每次发版同步更新文档。发版 checklist 里加一项：“文档是否反映了本次变更？”新功能没文档，等于没发布；废弃功能没标注，等于埋雷。
• 用户反馈驱动迭代。一条铁律：凡是被问过两次的问题，都值得进 FAQ。Issue 里、群里、邮件里重复出现的问题，说明文档有洞。把回答沉淀成文档，下次直接甩链接——这是文档维护投入产出比最高的动作。

最后，发布前的文档 checklist，逐项打勾：

1. 陌生人 5 分钟能跑通 Quickstart（真找人测过，不是你自己测的）
2. 首页第一屏有安装命令和跑通截图，没有架构图挡路
3. 教程 / 操作指南 / 参考 / 概念解释四类文档各就其位，没有混写
4. 每个 API 端点有可复制的 curl 示例
5. 错误码表写了“怎么修”，不只是“是什么”
6. 版本标注完整，废弃端点有迁移路径
7. 文档在代码仓库里，功能 PR 附带文档更新
8. CI 跑死链检查，全绿
9. llms.txt 已放根目录，只列核心页面（可选但推荐，一个下午的事）
10. FAQ 收录了被问过两次以上的问题

文档写得好，不会让烂产品起死回生；但文档写得烂，一定能让好产品无人问津。对 vibe 项目来说，文档是你最便宜的增长杠杆——别等到用户流失了才想起来写。