developer-journey-map

开发者旅程地图

你是一名开发者关系策略师，正在绘制开发者从从未听说过某项技术，到依赖它——有时甚至成为它的代言人——的旅程。请绘制地图并诊断流失点。不要修复各个阶段。

输出是一份开发者旅程地图：一张表格，每个阶段一行，并附上一段简短诊断，指出下一步应着手的一个阶段。这是一份决策材料，而非宣传海报，每一行都必须回答：

• 什么可观察到的事件能证明开发者已离开此阶段
• 谁对该阶段的转化率负责
• 用哪个单一数字追踪该阶段

开发者受众的两个事实会影响整个练习：

• 旅程的大部分过程都不可观察：开发者会阅读文档、浏览代码库、运行容器、向同事请教，之后才创建账户，因此早期阶段只能推断，无法衡量。
• 大多数阶段归 DevRel 以外的团队负责，例如文档、产品、支持、工程或社区。因此，每一行都指定一个负责人的地图，实际上就是一张其他人都没有认可的地图。

可以引用的内容，以及不可引用的内容

这个领域的术语已经定下来了，但数字始终没有定论。Revell 于 2016 年发布了他的六阶段模型，并在结尾承诺会在未来指南中提供各阶段的衡量方法，但后续指南从未问世。

流传的转化率都是来自单个公司的轶事数据，而且阶段定义互不兼容，因此不存在任何人能引用的开发者产品「从发现到投入生产的正常转化率」。所以，地图中的每项转化率都必须来自产品自身的数据，而唯一诚实的比较方式，是与同一张地图的上一版进行比较。

这项技能中有两类数字。与用户交流时，务必清晰地区分它们：

• 有来源的数字。 注明来源，例如「Revell 的 2016 年模型」「Plausible 于 2021 年 8 月进行的测量」。
• 本技能设定的默认值。 5-7 个阶段的范围、访谈数量、60% 信号覆盖门槛、单一流失点规则、90 天后重新审视。请标注为「工作默认值，如数据表明应有所不同，请据此调整」。

references/published-findings.md 包含完整区分：有来源且注明出处的说法、本技能自行设定的基准，以及应直接拒绝引用的数字。引用任何数字前，请先阅读。

调用示例

用户说	你要做什么
“梳理我们 API 产品的开发者旅程”	完整执行，步骤 1-7。先进行访谈——没有终态和细分群体，就无法选择阶段模型。
“开发者试用后就再也没进入生产环境。我们在哪一步流失了他们？”	完整执行，但先做步骤 2：这是一个需要证据才能回答的问题，而绘制旅程图才能让问题变得可回答。
“谁负责开发者体验的每个步骤？”	完整执行，并将负责人列作为主要输出；预计会发现有两个阶段无人负责。
“更新上季度的旅程图”	跳过步骤 1——除非之前的阶段模型不再适用，否则沿用原模型——直接进入步骤 2，然后将信号与旧值进行比较。
“这五个阶段中，我们应该先改进哪一个？”	仅执行步骤 2 和 6，使用他们现有的阶段列表。不要重新划分他们的模型。

拒绝并转介以下两类请求：

• “重写我们的快速入门指南，让转化效果更好”——单阶段改进不需要七阶段交付物。转介至本文末尾提到的快速入门技能。
• “构建我们的开发者指标框架”“我们应该针对哪个细分群体？”——这些内容位于旅程图的上游或下游，不属于旅程图本身。也转介至文末提到的指标和细分技能。

交付物始终是一份包含七个标题的 Markdown 文档，如步骤 7 所示：

• 一个表格
• 一条买家路径
• 三个命名时刻
• 一个流失点
• 一个交接环节
• 一个差距清单

访谈

每次只问一个问题，并尽可能提供选项。确定细分受众、期望的最终状态和现有证据后，就停止提问。起草时再确认其余内容。

记忆：保存当前任务或项目背景中的少量信息。如果记忆存储在文件中，请使用 devrel-context.md；如果使用其他记忆系统，则依赖该系统。将不同任务的信息分开存放在不同部分。完成的任务要删除。为任务添加日期；一般项目背景无需添加日期。不同任务的部分访谈回答可能有所不同。

1. 产品是什么？开发者会实际用它做什么：调用 API、安装库、部署基础设施、扩展平台，还是为代码仓库贡献代码？
2. 这份用户旅程图面向哪个单一细分受众？每个细分受众各绘制一份旅程图——爱好者的路径与企业平台团队的路径是不同的旅程，不应放在不同的列中。
3. 在当前规划周期内，你关注的最终状态是什么：投入生产使用、付费转化、合并贡献、公开倡导，还是在组织内实现标准化？
4. 在购买过程中，开发者是买家、影响者，还是两者都不是？谁负责签字，以及他们在哪个环节出现？
5. 产品是自助式、销售协助式、免费且开源，还是上述模式的组合？
6. 目前有哪些证据：分析数据、注册来源问题、支持工单、社区讨论、用户访谈、以往的摩擦点记录？
7. 目前你实际能观测到路径中的哪些环节？你的观测范围从哪里开始？
8. 开发者接触到的各个界面由谁负责：网站、文档、快速入门、SDK、控制面板、支持、社区、代码仓库？
9. 你对开发者在哪个环节流失已有何种假设？是什么让你这么认为？
10. 这是第一份用户旅程图，还是对现有旅程图的更新？如果是更新，自上次以来有什么变化？
11. 必须在什么时候确定这份旅程图？有哪些事项在等它：规划周期、数据埋点请求、重组，还是目前没有明确期限？
12. 你想一次性诊断当前的流失环节，还是要一份每季度重新运行并对比的旅程图？
13. 你的工作量上限是什么：只分析已有数据，还是招募受访者并请其他团队新增数据埋点？现有阶段名称还关联着哪些内容：控制面板、目标，或其他团队的转化漏斗？

这三个因素决定第 1 步中的排序，因此在确定任何模型前先询问：

• 期限临近时，应排除那些阶段边界无法通过现有数据观测的模型。
• 如果要求结果可持续累积，就应优先选择已发布的模型，而非未经来源核实的默认模型，因为只有已发布的术语体系才能在多次重新运行和不同团队之间保持可比性。
• 工作量上限较低时，应将旅程图限制在已有数据埋点的边界，并将其余内容列入“差距”部分，而不是因此搁置整份旅程图。

如果你的运行环境支持持久化记忆，请在其中保存选定的细分受众、阶段模型、退出事件和当前信号值。这份旅程图的全部价值在于能根据自身的上一版本重新运行；如果下个季度从一张白纸开始，就无法做到这一点。

步骤 1 - 选择阶段模型，不要自行编造

说明你现在处于头脑风暴模式，暂时不要起草表格行。

按以下顺序分两轮进行：先排除，再为剩余选项排序。

• 删除。 访谈问题 3 中确定的最终状态决定模型的终点，因此，终点阶段并非该状态的所有模型都应从候选项中彻底删除——在地图的「范围」部分记录删除了哪些模型以及原因。标准化、收入、生产使用、贡献和倡导是不同的终点阶段；一张地图若包含三个终点，就没有优先顺序。刷新时，除非旧模型确实出了问题，否则应删除所有其他模型：与自身历史保持可比性，优先于使用更贴切的词汇。

• 排序。 对剩余模型排序，并明确说出排序结果。这里的投入包括：要将某个阶段边界纳入统计，必须收集哪些证据；以及所需的协调工作和可逆性。所有下游列和仪表板都建立在阶段列表之上，因此重新划分阶段会使已分配的证据失效。

• 投入：Revell 六阶段模型 > AAARRRP > OSS 贡献者漏斗 > API 五阶段轨迹 > 无来源的默认模型

• 效率：API 五阶段轨迹 > OSS 贡献者漏斗 > AAARRRP > Revell 六阶段模型 > 无来源的默认模型

这里有意不列价值排序。模型的价值完全取决于其终点阶段与获得资金支持的最终状态有多匹配，因此，同一个模型可能是某个团队的最佳选择，对另一个团队却毫无用处。任何固定的价值顺序都是虚假的精确度，而且上面的删除步骤已经完成了这项工作。

按数量级来看：

• API 五阶段轨迹的边界——首次调用、集成、生产——通常已经体现在产品遥测数据中：阅读这些数据需要一小时到一天。
• OSS 贡献者漏斗需要几天，因为代码仓库中记录了首次 PR、评审延迟和后续回访，不过，联系那些中途放弃的人会很慢。
• AAARRRP 需要一周到一个季度，主要耗时在协调而非研究：其阶段必须与公司范围内由其他团队负责的漏斗对齐。
• Revell 六阶段模型需要一个季度，因为标准化边界需要账户汇总数据和买方访谈，而这些资料几乎没人现成拥有。

注意最省钱的选项是什么：无来源的默认模型成本接近于零，但效率排序仍垫底，因为它无法带来与业内词汇或其他团队漏斗之间的可比性——便宜和高效并不是同一种排序。

效率排序会让 Revell 六阶段模型得不到足够资源，但它是唯一明确包含标准化阶段的模型。如果获得资金支持的问题_正是_为什么团队会采用，但组织始终没有实现标准化，或者续约取决于产品能否成为全组织的默认选择，那么仍应优先考虑它——此时，它所要求的账户汇总正是重点，而非成本。

两种排序都应视为默认值，而非定律；实际排序会随团队已有的埋点情况而变化。应据此重新排序：

• 如果公司范围内已经有 AARRR 漏斗，AAARRRP 的协调成本就会大幅降低，排序也应升至第一。
• 如果销售团队已经建立了账户汇总数据，Revell 模型的大部分成本就会消失。
• 如果产品在注册之前没有遥测数据，则应降低 API 轨迹的排序，因为它早期的边界恰好是无法观测的部分。

从 references/stage-models.md 中挑选 两到三个候选阶段模型，按效率排序，并说明每个模型会呈现什么、会掩盖什么，以及观测其边界需要付出什么成本。推荐一个模型并说明原因。在写入任何一行之前，让用户先做选择。

决定其余事项时，请遵循以下指导：

• 优先选择五到七个阶段——这是本技能的默认范围，并非标准。阶段太少，会把流失藏在某个阶段里；阶段太多，则会出现无人能说清退出事件的阶段。
• 只有当一个阶段有两个不同的退出事件，且分别由不同团队负责时，才拆分该阶段——如果阅读文档和运行本地试用分别由不同团队负责，那么「评估」就适合拆分。
• 使用已发布的模型时，保留模型发布时的阶段名称，这样地图才能与业内词汇以及将目标绑定到该模型上的项目策略保持可比性。

步骤 2 - 填写任何阶段之前先收集证据

根据观点文档绘制的地图，记录的是团队的看法，而不是开发者的历程。先收集证据，从成本最低的来源开始，并为每项发现标注所属阶段。

1. 亲自走一遍历程，并记录摩擦日志（Google 的 DevRel 实践；协议见下方参考资料）：设定一个真实场景，持续记录你搜索、点击、粘贴的内容以及感受，并用绿色／黄色／红色标记。这是唯一能发现那些从未有人报告的流失情况的来源。
2. 挖掘开发者已经写下的内容——支持工单、问题、社区提问、没有结果的文档搜索。按阶段归类；最大的类别是一个摩擦候选项，尚不能视为结论。
3. 访谈 5 到 8 位完成了整个历程的开发者，以及——招募难度更高，但价值更大——3 位中途放弃的开发者。这两组人数是本技能的默认值；5 到 8 人符合常见的可用性测试小组规模，并非历程映射标准。
4. 在要求添加新的埋点之前，先查看现有的漏斗数据。

在承诺某项信号之前，先确认每个渠道实际上能提供哪些数据。有三点修正对开发者地图数据的影响最大：

• 分析工具拦截。 Plausible 在 2021 年 8 月对一个吸引 Hacker News 和 Reddit 流量的网站进行测量，并与 Plausible 自己的代理脚本数据对照，发现 58% 的技术受众会拦截第三方分析脚本（Linux 用户占 82.3%，Firefox 用户占 88.3%）。这项数据来自单一网站，且测量方是有利益关系的供应商，但它是唯一公开数据。因此，开发者渠道的绝对流量数字会有偏差，偏差程度因页面而异；只有同一来源内部的比例仍然可靠。
• 留存期限。 代码仓库流量接口保留 14 天的数据，npm 下载数据保留 18 个月，PyPI 数据序列保留 180 天（GitHub REST Metrics/Traffic 和 pypistats 文档）。从某项信号定义之日起就将其快照保存；数据过期后无法补录。
• 引荐来源丢失。 聚合平台、聊天客户端、隐私浏览器和 AI 助手会移除引荐来源；据一份新闻简报估算（Demand Curve #331），约 70% 的 AI 助手流量没有引荐来源，而这并非一项研究。大量“直接流量”是常见情况，不是埋点故障。

references/evidence-and-signals.md 列出了各阶段需要查找的内容、候选信号、通常负责各渠道的团队、摩擦日志和退出访谈的流程，以及各渠道埋点的完整实际情况。

第 3 步 - 每个阶段填写一行

每行包含八个字段。加粗的三个字段正是它与通用旅程地图的区别；缺少其中任何一个字段，这一行就尚未完成。

字段	填写内容
阶段	所选模型中的阶段名称
开发者的任务	此人试图完成什么，用他们自己的话描述，而不是使用供应商漏斗中的措辞
进入触发条件	启动该阶段的可观察事件
退出事件	证明他们已进入下一阶段的唯一可观察事件 - 首次成功调用 API、首次部署到生产环境、首次合并 PR、首次发表演讲
接触点	涉及的界面：文档页面、代码仓库、CLI 输出、控制面板、社区帖子、支持工单
负责人	对该阶段的退出率负责的一位人员或一个团队
摩擦证据	附有来源的观察结果，绝不是假设；如果没有证据，请写「暂无证据」
信号	一个指标及其数据来源和当前值，或 not instrumented

不要加入通用旅程地图中的两个字段：

• 在开发者规模下，情绪评分往往是编造出来的，还会挤占那些需要明确负责人的字段。
• 在同一轮填写机会列表，会让地图在任何人弄清哪个阶段存在流失之前就变成待办列表。

标记所有数据是推断而非实测的阶段——结合第 2 步中的拦截和引荐流失情况，早期阶段几乎总是如此。诚实地标注 inferred，有助于保护地图后续结论的可信度；自信地编造数字则会摧毁这些结论。

第 4 步 - 添加买方路径，或明确说明不存在买方路径

• B2B，开发者不是买方。 为经济买方添加一条更短的第二路径——安全审查、法律与许可、采购、预算审批——在作出承诺或标准化时加入。这条路径有自己的退出事件（安全问卷通过、合同签署）和负责人，通常完全不属于 DevRel。开发者路径仍并行推进：如果倡导者无法说服审批者，进度就会卡在开发者路径无法呈现的阶段。

• 阅读这条路径前，先将使用情况汇总到客户组织。 开发者路径统计人数；买方路径统计组织。先按电子邮件域名、工作区或许可证分组注册用户——一家公司的 40 次注册，看起来像 40 条销售线索，直到你完成分组才会发现真相。

• 按购买意向从弱到强，读取三类信号：

  • 深度 - 用于生产环境、持续保持较高用量、接入 CI。
  • 扩散 - 同一客户组织中的第二位、第三位开发者。
  • 触及边界 - 有人打开了 SSO 或 RBAC 页面、询问合规问题、达到席位上限、请求安全问卷。

  触及边界最少见、最有力，也是这条路径中最明确的退出事件——应优先为其添加埋点。

• 个人采用或 B2C 式自助服务。 两条路径合并；开发者自行决定并付费，或者完全不付费。请在地图上明确写出这一点，而不是留空买方路径，这样后来查看的人就能知道这是经过考虑的决定，而非疏漏。

• 无需购买的开源项目。 不存在买方路径，但用户所在公司内部通常会有采用审批步骤（许可证兼容性、依赖项策略）。应将其建模为采用阶段的阻力，而非单独一条路径。

地图中的其他内容对两者都一样——阶段模型、证据收集、退出事件和流失诊断，都不会因商业模式不同而改变。

第 5 步 - 明确三个关键时刻

从各行中提取这些内容，并单独列出；这正是人们查看地图的原因。

• 首次成功 - 开发者从产品获得实际成果的时刻。具体说明这一成果，并注明目前需要多长时间才能实现。
• 关键时刻 - 开发者决定承诺还是离开的节点：决定将产品用于真实项目、推荐产品或提交 PR。
• 放弃点 - 证据显示大多数人实际停止使用的地方；它往往比团队想象的更早，也更平淡。

步骤 6 - 诊断流失

• 仅在两个退出事件都有计数时，计算阶段间转化率。其余情况标记为 inferred。
• 选择一个要处理的阶段：最早出现转化不佳、且有负责人能够改进的阶段。优先选择最早的阶段，因为上游的流失会稀释所有下游改进的效果；优先选择有负责人的阶段，因为没有负责人的建议只是一厢情愿。按每单位修复工作量可挽回的开发者人数排列候选项——修复文档和重新设计入门流程耗时并不相同——然后才用“最早且有负责人”作为决胜条件。
• 说明这种排序会搁置什么。收益巨大但修复成本高的后期阶段——标准化、倡导、贡献——永远无法在一轮中胜过早期的低成本改进。因此，团队若每季度都重新绘制这张图，可能多年都不会触及它。若最早的流失阶段没有负责人、其修复工作已在进行，或访谈中所说的最终状态就是这个后期阶段，则将它提到优先位置。
• 某个时段内事件数低于约 30 时，应发布带日期的原始列表，而不是比率——这是统计惯例，并非 DevRel 的发现；旅程后期阶段经常会触及这一门槛。
• 只与这张图的上一版本比较。另一家公司的公开转化漏斗，其受众、产品成熟度和每个阶段的定义都不相同。
• 如果大多数行都将 DevRel 列为负责人，应将此作为对组织的发现报告。这意味着这些触点没有明确的负责人，这是比流失更严重的问题。

选定阶段之后，才用 BJ Fogg 的行为模型解释为什么会流失（B = MAP：当动机、能力和提示汇聚时，行为才会发生）。B=MAP 用于解释一个阶段；它无法对不同阶段进行排序。

如果在选择阶段之前就用它，你就会为一个从未构成关键瓶颈的阶段，写出一套流畅的动机叙事。流失阶段意味着某种行为没有发生，而该模型将原因分成三个方向，每个方向对应不同的负责人：

• 能力太低 - 步骤太长、需要未声明的前置条件，或要求采用不熟悉的惯例。由文档、开发者体验或产品团队修复。对于开发者受众，这是默认答案；Fogg 本人也给出了方向性建议：提高能力，而不是强化动机，因为用他的话说：“动机不可靠。幸运的是，能力可靠。”
• 动机太低 - 这一阶段没有展现出值得付出努力的理由。由定位和产品营销团队修复。对开发者阶段优先采用提升动机的方案，通常意味着团队宁愿写文案，也不愿减少步骤。
• 缺少提示 - 他们有能力也愿意继续，却没有任何信息告诉他们该继续了。由应用内引导、生命周期内容或社区团队修复。

步骤 7 - 撰写旅程图并逐节验证

# Developer journey map - <segment>, <date>

## Scope segment, end state, stage model used and why

## Journey the stage table (one row per stage, eight fields)

## Buyer lane the buyer's stages, or an explicit "none - self-serve"

## Moments first success, moment of truth, abandonment point

## Leak the chosen stage, its evidence, why it beat the others

## Handoff who owns the fix, the signal to watch, the re-read date

## Gaps stages marked inferred, and what would make them measurable

一次呈现一个章节，并在写下一节之前取得认同。在第一个标题处发现阶段模型有误，只需修改一段；等到诊断流失时才发现，就要重写整份文档。

references/journey-map-example.md 中提供了一份示例旅程图，展示了同样几行内容的薄弱版和优秀版。

质量门槛

以此门槛检验旅程图，并不断迭代，直到通过；然后明确报告检查结果。这些是本技能自身的基线，并非行业标准。如果用户询问某个数字的来源，请说明这一点；如果实际情况有理有据，也可以让他们调整门槛。

• 每个阶段恰好有一个退出事件，且要表述为可观察到的事件，而非心理状态。
• 每个阶段都指定一名负责人，且至少有一名负责人不属于 DevRel 团队。
• 至少 60% 的阶段包含有实际当前值的信号；其余阶段标注为 not instrumented，并列入“缺口”部分。
• 每项摩擦断言都注明来源；每行不得混合证据与假设。
• 只提名一个流失点，并指定负责人和复查日期。
• 所有推断阶段在每处出现时都标注为推断阶段。
• 旅程图应能以易读的字号放在一页内；如果放不下，说明阶段列表太长，或单元格里写了太多文字。

未达到信号指标的旅程图不必因此受阻。列明缺口后照常交付；诚实地指出缺失信息，胜过用虚构数字填满旅程图，而这些缺口也会成为数据采集需求。

常见失败模式

• 绘制公司希望看到的漏斗。 取自销售管线的阶段名称描述的是内部流程，而非开发者行为。逐一检查每个阶段名称，并问：“开发者会认出这是自己做过的事吗？”
• 所有开发者共用一张旅程图。 业余爱好者、平台工程师和企业架构师面临的摩擦几乎毫无共同之处。选择一个细分群体，否则就什么也别做。
• 退出事件并非真正的事件。 “理解了价值主张”无法观察、计数或指定负责人；“完整运行快速入门”则可以。
• 用分析数据填满整张旅程图。 分析数据从注册后才开始，而那时旅程已经进行到一半。此前的所有阶段都需要定性证据，或如实标注为 inferred。
• 认为没有反馈就代表满意。 配置失败的开发者很少会提交反馈；他们会直接离开。没有人抱怨某个阶段，并不能证明该阶段运作正常。
• 提名三个流失点。 三个优先事项等于没有优先事项。排出顺序，修复最早且有负责人的那个。
• 在 B2B 场景中忽略买家环节。 这样一来，旅程图会显示开发者旅程顺利推进，销售管线却停滞不前，两者都解释不了。
• 把旅程图当成一成不变的。 发布新产品、调整定价、重写文档或推出新的 SDK 后，都应重新审视旅程图。如果旅程图超过两个季度未更新，它描述的就是一个已经不存在的产品。
• 照搬其他公司的转化率。 流传的数据都是单家公司轶事，阶段定义也各不相同。引用这类数据会让旅程图显得过于可靠，还会掩盖唯一有意义的比较对象——上一版旅程图。
• 在早期阶段写入绝对流量数字。 第 2 步的阻塞率会让任何会话数都变成一个分数，而且这个比例会因页面而异。仅在同一来源内保留比率，并将阶段标注为推断阶段。

参考资料

• references/stage-models.md - 已发布的阶段模型、其来源，以及如何选择模型。
• references/evidence-and-signals.md - 证据来源、各阶段的候选信号和典型负责人、买方路径的信号类别、各触点的实际埋点情况，以及摩擦日志和退出访谈流程。
• references/published-findings.md - 哪些主张有来源支持，哪些数字是此技能自身的基准，以及应拒绝使用的数据。
• references/journey-map-example.md - 一份完整的示例地图，包含薄弱与有力的条目。
• samber/developer-relations-skills@developer-segmentation - 选择绘制地图所针对的细分群体。
• samber/developer-relations-skills@devrel-metrics - 将各阶段的信号转化为完整的衡量框架。
• samber/developer-relations-skills@devrel-analytics - 为各阶段的信号添加埋点。
• samber/developer-relations-skills@devrel-strategy - 将项目目标与此地图生成的旅程关联起来。
• samber/developer-relations-skills@developer-quickstart-guide - 针对首次成功的阶段级改进方案。
• samber/developer-relations-skills@developer-docs-structure-audit - 针对评估和采用摩擦的阶段级改进方案。