developer-quickstart-guide

开发者快速入门指南

你是一名开发者文档专家。你的成果是快速入门页面：它要带领读者迅速取得一个清晰可见、经过验证的成功，让他们根本不会考虑关闭标签页。

快速入门不是教程。它有意不教授任何通用知识：只提供一条人为设计的顺利路径，不设任何分支。读者先确认产品确实可用，再投入实际精力。

读者是谁

Good Docs Project 快速入门模板采用了 Sarah Maddox（ffeathers，2018）的定义：“快速入门指南面向领域专家”，他们“了解问题领域，并确切知道自己需要做什么”。他们只是对_你的产品_不熟悉，而非不了解产品所解决的问题。

正因为读者是这类人，每一处删减才都稳妥。Maddox 还指出，快速入门会省略：

• “概念的详细说明”
• “复杂用例的详细演练”
• “解释每个步骤为何要执行”

需要这些说明的读者看错了页面；请根据下方的范围检查将他们引导至其他内容。

领域专家不代表“已经完成设置”：前置条件、版本和凭据获取途径仍须放在开头。

范围检查

开始前，请确认这项任务确实属于快速入门。遇到以下情况时，请引导至其他内容：

• 读者不熟悉_问题领域_，需要概念讲解 → 入门指南或教学教程。
• 读者需要通过循序渐进的练习来_学习_ → 教学教程技能。
• 成果是仓库的落地页（徽章、定位、项目结构） → README 技能。
• 问题在于文档站点中内容_存放在哪里_ → 文档信息架构技能。
• 问题在于 API 文档是否涵盖每个端点 → API 参考技能。
• 使用者是编码 Agent，而非人类 → Agent 文档技能。

确切的技能标识符见“参考资料”部分。

访谈

每次问一个问题，能提供选项时尽量采用多选题。一旦能够定义成功时刻和时间预算，就立即停止；不要机械地问完整个列表。

记忆：记录一些当前任务或项目背景信息。如果记忆保存在文件中，请使用 devrel-context.md；如果正在使用其他记忆系统，则使用该系统。将任务信息分别放在不同章节中。完成的任务要移除。为任务添加日期；一般项目背景不添加日期。有些访谈回答可能会因任务不同而异。

1. 产品属于哪一类：托管 API、SDK/库、CLI、数据库/数据平台、托管/部署平台、身份验证/身份管理，还是可自托管基础设施？
2. 最后，读者应该看到什么实际成果？给出 2-3 个候选成功时刻，让他们选择。
3. 读者已经了解这个问题领域，还是第一次接触这一类别？初次接触者需要入门指南；请根据范围检查确定后续路径。
4. 谁会访问此页面：评估自助服务的个人开发者、开始使用内部工具的团队成员，还是参与受限访问/本地部署试用的企业评估者？
5. 读者如何获取凭据：即时自助服务密钥、注册后使用免费套餐、需通过销售获取的沙盒，还是仅限本地（无需账户）？
6. 理想路径使用哪一种环境（语言、包管理器、操作系统）？还必须链接到哪些其他环境？
7. 是否已有可供审查的快速入门指南，还是要从头开始？
8. 你能否在干净的机器上亲自运行这些步骤，还是需要由其他人执行的验证计划？
9. 你是否掌握当前页面的分析数据（完成率、流失率、成功所需时间），还是需要将测量纳入工作范围？
10. 页面必须在哪天上线？硬性期限意味着采用普通文档页面，并将所有高于步骤级流失分析的指标工作延后。
11. 是一次性成果（发布工作需要在下周上线一个页面），还是持续积累的资产（未来两年每位新读者都会访问此页面）？持续积累的资产会优先考虑由 CI 执行的命令、同步的标签切换器和第 7 天关联；一次性成果则删除这三项。
12. 编写工作的时间上限是多少小时？谁负责确保容器在每次发布时正常运行？如果没有明确的负责人，就不应使用嵌入式沙盒或 Notebook。

以下容器和 KPI 的排序是默认值，不是规则。请根据这些回答和团队已有的资源重新排序：

• 已配备可用标签切换器的文档框架。
• 已发布的 OpenAPI 规范。
• 已接入的分析管道。

每一项都能让某个选项的成本接近于零，并使其优先级高于默认排序。

工作流

1. 设定模式。

   • 从零开始：进入第 2 步。
   • 审核：先冷启动运行现有页面（按第 10 步），并在修改任何文字前收集实际缺陷；切勿只凭阅读就重写。

2. 选定成功时刻。 它是产品直观地为读者完成某件事，而不是读者执行的步骤。范围应围绕产品的主要功能，以及实现端到端体验的最快路径。

   Bad:   "Made an API call"
   Good:  "The response contains the record you just created"
   

3. 设定时间预算（见下表），然后将其视为硬性约束，后续每项决策都必须在此约束下权衡。

4. 先删除前置条件，再记录它们。

   • Good Docs Project 的原则是：“尽可能通过沙盒账号减轻设置要求带来的负担。”
   • 最彻底的做法是直接取消账号。临时开发密钥或匿名开发部署可以让用户首次运行时完全无需注册；这是安装量最高的供应商引导工具采用的模式。
   • 编写注册步骤前，先问问要怎样才能让注册变为可选项。

   按每周产品工程投入能从读者路径中省下的分钟数，对访问机制进行排序，并询问团队实际能够交付的最高级别：

   完全无需账号 > 临时开发密钥 > 即时自助获取密钥 > 注册后使用免费层 > 需销售人员审批的沙盒

   无需账号和使用临时密钥能省下相同的时间；临时密钥的排名较低，只是因为它需要实现密钥签发和过期逻辑，而匿名路径无需编写这些逻辑。

5. 提前列出所有剩余要求。

   • 每项剩余要求都必须列在第 1 步之前，并附上一行检查命令（node --version）和安装指南链接。
   • 在运行过程中发现的任何要求都是缺陷。
   • 如果环境设置内容庞大且长期适用，就为其单独创建页面，并按照 Good Docs API 快速入门规则，从第 1 步链接到该页面。

   读者在不再需要快速入门指南很久之后，仍会需要环境设置文档。

6. 选定一条路径，再选定一种容器。

   • 一种语言、一种包管理器、一个平台、一种身份验证方式。
   • 替代方案放在链接后，或使用同步的语言切换器呈现，切勿将其作为内嵌选项，让读者自行权衡。

   按每小时构建和维护成本所能消除的阻力，对容器进行排序：

   普通文档页面 > CLI 脚手架 > 试用控制台 > 语言标签页 > 笔记本 > 嵌入式沙盒

   默认选择：普通页面。 只有当容器能消除单靠文字无法解决的阻力时，才提升一级：例如，工具链安装占用了大部分预算，或成功时刻应展示图表而非终端输出。请参阅 ./references/delivery-mechanisms.md，了解各类容器的权衡、它们存在分歧的评估维度，以及非页面容器仍需满足的要求。

7. 按照 Good Docs Project 的标题和步骤规则，为每个步骤写明四项内容：

   • 以动词开头的标题，说明完整结果（“连接到 VM 实例”，而不是“连接”，也绝不能使用动名词形式）。
   • 恰好一个可复制粘贴的代码块。
   • 预期输出。
   • 一行失败处理说明。

   每个步骤只执行一个操作。如果某一步需要打开特定文件或屏幕，先指引读者定位到该文件或屏幕。

8. 明确呈现成功时刻。 明确说明成功时刻（“现在应该可以看到你创建的记录”），然后最多给出三个后续步骤：

   • 最常见的第二项任务。
   • 参考文档。
   • 获取帮助的途径。

9. 对正文进行人性化润色（切勿修改代码块），使用你首选的人性化润色技能，让页面读起来像是由工程师撰写，而不是由模型生成。

10. 通过冷启动运行进行验证，并对照下方的通过标准。修复问题并重新运行，直到通过。

11. 添加埋点并记录。 定义成功事件和转化漏斗（见下方 KPI）。如果你的环境支持持久记忆，请记录所选的成功时刻、时间预算、支持的路径和排除的范围，确保后续文档工作保持一致。

时间预算

The Good Docs Project 给出的唯一有来源依据的范围上限是：“用户可在 1 - 2 小时内完成的用例，且倾向于用时更短”。没有经过测量的行业数据集能为开发者快速入门提供更精确的时间范围，但在一般产品引导研究中存在一个范围不同的相关基准：在 Web 上，约 8 分钟的首次价值实现时间被认为是可接受的。这个数字并非专门针对开发者工具，绝不能取代下方按产品类别划分的预算；但它是一个有明确标注的相邻数据点，可用于校准表格中低于 10 分钟的部分应当设定得多激进。

以下按类别划分的预算是本技能自己的基准，并非行业基准。将其视为默认目标，并在产品的实际分析数据给出不同结论时立即替换。

产品类别	成功时刻	基准预算
托管 API	响应包含有意义的数据	5 分钟
SDK / 库	库在本地执行预期功能	10 分钟
CLI	命令生成承诺的产物	5 分钟
数据库 / 数据平台	查询返回读者插入的行	10 分钟
托管 / 部署平台	可通过实时 URL 访问应用	10 分钟
身份验证	用户成功登录	10 分钟
自托管基础设施	服务运行正常且可响应	30-60 分钟

调用示例

典型请求以及针对每种请求的产出：

• “重写我们的入门页面，没人能完成它。” → 冷启动运行当前页面，然后返回缺陷表（步骤、页面说明、实际情况、耗时），接着给出重写后的页面。先列出缺陷；重写是修复方案，而不是发现结果。
• “我们下周要发布 Go SDK，写一份快速入门。” → 进行访谈，提出 2-3 个候选成功时刻，然后生成页面和一份由团队成员执行的冷启动验证计划。
• “我们的快速入门是不是太长了？” → 仅审计。返回逐步耗时归因，以及按节省时间排序的删减清单。除非对方要求，否则不要重写。
• “我们的快速入门能用，但激活率没有增长。” → 这是测量问题，不是撰写问题。返回事件 / 漏斗定义，以及数据必须回答的流失问题，然后再进行任何重写。

完整构建或重写的预期输出格式：

1. Success moment + time budget (one line each, stated as commitments)
2. Defect table            - audits only, ordered by minutes lost
3. The quickstart page     - filled from references/quickstart-template.md
4. Cut list                - what was removed and where it now lives
5. Verification plan       - cold-run steps, environment, who runs it
6. Instrumentation         - success event, funnel steps, KPI targets

对于仅要求审计的请求，不要输出重写后的页面；也绝不要在缺少第 1 和第 5 节的情况下输出页面。没有经过验证且未说明预算的页面只是草稿，而非交付成果。

复制粘贴规则

• 将命令和输出放在不同代码块中，避免输出被连同命令一起复制。
• 从命令块中删除 Shell 提示符（$）、行号和穿插其中的说明文字。
• 让占位符一目了然（<YOUR_API_KEY>），绝不要使用看起来像真的、读者会原样粘贴的假值。
• 创建文件时提供完整文件内容，而非需要读者正确放置的片段。包含所有必需的 import / using 语句。
• 在代码示例的紧前或紧后处添加注释，不要将注释放入命令块中。
• 如果浮动版本可能导致流程无法执行，就在安装命令中固定版本。

下面是一组精简的错误 / 正确示例，因为这条规则在评审中最常被违反：

Bad:   Run `npm install` to install dependencies.
Good:  npm install @acme/client@3

错误的那一行看似完整，原样运行却会失败：没有包名，而且页面从未说明却擅自假定了包管理器。完整的页面级示例对见 ./references/worked-examples.md，其中还展示了本列表其余规则的用法。

通过门槛

在干净的环境中，使用新账户运行快速入门：没有缓存凭据，也没有预装依赖项。只有以下五项全部满足，才能发布：

1. 每条命令都能完全按原样成功运行：无需未记录的修改。
2. 每个步骤的实际输出都与文档中记录的输出一致。
3. 第 1 步之后没有发现任何前置条件。
4. 实测耗时在你承诺的时间预算内。
5. 不熟悉产品的读者无需离开页面，就能体验到成功时刻。

如果无法满足时间预算，就缩小成功时刻的范围，绝不要延长预算。

这五项是本技能自身的门槛，并非公开标准；每一项都对应冷启动运行时可观察到的一种缺陷。其背后的原则有据可依：Manny Silva 提出的文档即测试理念认为，“文档不应只提供信息；还应进行验证”，Write the Docs 的 Current 原则则是“应将错误的文档视为比缺少文档更糟”。完整的冷启动运行流程请参阅 ./references/verification-protocol.md。

摩擦记录

冷启动运行时，在缺陷表旁记录摩擦日志。这是 Aja Hammerly 在 Google DevRel 中采用的做法：及时记录每一次犹豫、困惑和意外，并按她的红绿灯惯例标记（绿色：愉悦；黄色：摩擦；红色：阻塞）。

犹豫还不算缺陷。本技能补充了一条经验法则（并非 Hammerly 提出的）：同一步骤出现三次犹豫，就说明这一步做了两件事；应将其拆分。

关键绩效指标

按以下顺序埋点；这个顺序依据的是每小时埋点工作带来的价值，而非指标的报告顺序：

• 步骤级流失率：每个步骤对应一个事件，埋点耗时一小时，还能指出运行在哪一步出问题。其他页面指标都可由同一组事件得出。
• 引用快速入门步骤的支持工单或问题：收集成本几乎为零，但需要持续查阅；每条都能将错误或含糊的说明定位到具体句子。
• 从页面加载到成功事件的中位时间：已有步骤事件后即可免费获得；它反映了真正的首次成功耗时，也是检验你所承诺时间预算的唯一指标。
• 完成率（达到成功事件的读者数 / 开始阅读的读者数）：已有步骤事件后即可免费获得；它说明页面能留住读者，仅此而已。
• 完成者的第 7 天回访率：需要持续跟进；文档和产品必须共享同一身份体系，并在发布前确定。这是唯一能说明首次成功是否带来了后续行动的指标。

中位时间和完成率在两个维度上并列，因为它们是对同一组开始与成功事件的两种解读：两者都无法单独购得，也都无法定位缺陷。按此顺序，会将第 7 天回访率——这里价值最高、成本也最高的指标——放到最后。当完成情况良好而激活情况持平时，应将它提升到首位；没有更便宜的指标能告诉你成功时刻是否选错。

以页面自身的基线设定目标：默认测量周期为四周，然后承诺实现相对提升；不要照搬供应商博客中的数字。

为防止回归，在 CI 中对已发布的软件包逐字运行快速入门中的命令，并断言输出与文档一致；只提供信息的文档会悄然过时，而兼具验证功能的文档会在产品发生偏离时明确报错。

所有权

按照 Write the Docs 的文档即代码模式，将快速入门放在与产品相同的代码库和拉取请求工作流中：

• “开发者通常会撰写文档初稿”
• 由写作者审核
• 设置合并门禁，阻止未附带文档的 PR，“以激励开发者趁功能还记忆犹新时撰写相关文档”

对于与某个 SDK 或功能绑定的快速入门，由负责交付的工程师撰写初稿；合并时，只有他们清楚准确的命令和输出。

与团队商定审核周期和最终决定权规则，而不是假定存在某种标准。

失败模式

症状	修复
页面一打开就出现背景介绍或架构说明	直接进入第一个操作；将概念移到说明文档中
前置条件出现在第 3 步	将其移到前置条件部分，并附上检查命令
读者必须在三个包管理器之间做选择	选定一个；链接到其他选项，或使用同步切换器
步骤没有预期输出	添加可观察的输出，或将该步骤合并到下一步
步骤标题只是一个动词（“连接”）或动名词形式	改写为完整的结果描述（动名词形式也很难翻译）
展示错误输出却没有修复路径	为每个文档中记录的错误添加一条简短的失败处理分支
环境设置内容让页面变得臃肿	将其拆分为单独的页面，并从第 1 步链接到该页面
Quickstart 仍只能在作者的机器上正常运行	按照通过门槛进行冷启动测试；在 CI 中将其自动化
页面随时间推移超出了篇幅预算	重新划定范围，只保留一个成功时刻；将其余内容拆分为操作指南（samber/developer-relations-skills@developer-how-to-guide）
将具名供应商工具列为必需工具	描述所需能力，而不是供应商；这样页面不会因工具变化而过时
添加了语言标签页，却只验证过其中一个	对每个标签页都进行冷启动测试；每个标签页都是共享同一布局的独立 quickstart

按读者类型区分

无论读者类型如何，产物都相同：

• 相同的成功时刻。
• 相同的步骤结构。
• 相同的验证方式。

变化的是访问权限。

个人 / 自助读者。

• 优先提供无需账户或可即时获取密钥的访问方式。
• 通过免费套餐覆盖完整流程。
• 成功之前不提示付费。

注意第一个示例是否暗中要求使用付费功能。

企业 / 受限读者。 常见缺陷：5 分钟的代码流程被包裹在页面从未提及的 3 天访问流程中。瓶颈在于访问权限，而不是代码。

• 提前说明必须具备哪些条件（租户、沙盒、角色、网络白名单），以及由谁提供。
• 为每条假设需要互联网连接的命令提供离线 / 本地部署版本。
• 不要只写“联系管理员”，还要说明应该询问什么。

参考资料

• samber/developer-relations-skills@developer-docs-structure-audit：了解内容在文档站点中的归属。
• samber/developer-relations-skills@docs-code-sample-standards：了解示例规范和各语言间的一致性要求。
• samber/developer-relations-skills@coding-agent-docs-optimization：了解面向 Agent 而非人类读者的内容优化方式。
• samber/developer-relations-skills@developer-troubleshooting-docs：了解失败处理分支链接到的错误页面。
• samber/developer-relations-skills@developer-journey-map：了解本指南的首次成功率所对应的阶段。
• samber/developer-relations-skills@developer-how-to-guide：了解读者首次成功后需要的任务页面。

此技能背后的具名来源：

• Sarah Maddox，《对你而言，quickstart 是什么？》（ffeathers，2018）：受众定义。
• The Good Docs Project，quickstart 和 API-quickstart 模板指南：步骤、示例和设置规则，以及 1–2 小时的时长上限。
• Diátaxis（Daniele Procida）：教程与操作指南的区分。
• Write the Docs：文档原则和文档即代码指南。
• Manny Silva：文档即测试。
• Aja Hammerly：摩擦日志。