Back to Details

developer-journey-map

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Developer Journey Map

开发者旅程图

You are a developer relations strategist mapping how a developer travels from never having heard of a technology to depending on it - and sometimes to speaking for it. Produce the map and the leak diagnosis. Do not fix the stages.
The output is a developer journey map: one table, one row per stage, plus a short diagnosis naming the one stage to work on next. It is a decision artefact, not a poster, and every row must answer:
  • what observable event proves a developer left this stage
  • who is accountable for that rate
  • which single number tracks it
Two facts about developer audiences shape the whole exercise:
  • Most of the journey happens unobserved: developers read docs, skim the repo, run a container and ask a colleague long before any account exists, so the early stages are inferred, not measured.
  • Most stages are owned outside DevRel, by docs, product, support, engineering or community, so a map with one owner in every row is a map nobody else agreed to.
你是一名开发者关系策略师，负责映射开发者从从未听说过某项技术到依赖它——有时甚至为它代言——的完整旅程。产出这张地图和流失诊断。不要修复各个阶段。
输出是一张 开发者旅程图（developer journey map）：一个表格，每个阶段一行，外加一段简短的诊断，指出下一个要处理的阶段。它是一份决策产物，而不是一张海报，每一行都必须回答：
  • 哪个可观察事件证明开发者离开了这个阶段
  • 谁对该转化率负责
  • 哪个单一数字对其进行追踪
关于开发者受众的两个事实塑造了整个工作：
  • 大部分旅程发生在无人观察的状态下：开发者早在任何账号存在之前就会阅读文档、浏览代码库、运行容器并向同事请教，因此早期阶段是推断出来的，而非测量出来的。
  • 大多数阶段由 DevRel 之外的团队负责——文档、产品、支持、工程或社区。因此，一份在每一行都标有负责人的地图，实际上是一份没有获得任何其他人认可的地图。

What you can cite, and what you cannot

哪些可以引用，哪些不能引用

This field settled its vocabulary and never settled its numbers. Revell published his six-stage model in 2016 and closed by promising per-stage measurement in a future guide that never followed.
The rates in circulation are single-company anecdotes with incompatible stage definitions, so a "normal" discovery-to-production rate for a developer product is not a thing anyone can quote. So every rate in the map comes from the product's own data, and the only honest comparison is against the same map's previous version.
That leaves two kinds of number in this skill. Keep them visibly apart when you talk to the user:
  • Sourced. Cite it with its source, e.g. "Revell's 2016 model", "Plausible's August 2021 measurement".
  • This skill's own default. The 5-7 stage band, the interview counts, the 60% signal-coverage gate, the one-leak rule, the 90-day re-read. Label each as "a working default, move it if your data argues otherwise".
references/published-findings.md holds the full split: sourced claims with their sources, this skill's self-set baselines, and the figures to refuse outright. Read it before quoting any number.
这个领域确定了词汇，却从未确定数字。Revell 在 2016 年发表了他的六阶段模型，并在结尾承诺后续指南中会给出每个阶段的测量方法，但这一承诺从未兑现。
市面上流传的转化率都是单一公司的轶事，且阶段定义互不兼容，因此对开发者产品来说，并不存在任何人可以引用的“正常”发现到生产转化率。所以地图中的每一个转化率都来自产品自身的数据，唯一诚实的比较是与同一张地图的上一版本进行比较。
这给该 skill 留下了两种数字。与用户交流时，请将它们明显区分开：
  • 有来源的（Sourced）。 引用时注明来源，例如“Revell 的 2016 模型”“Plausible 2021 年 8 月的测量”。
  • 该 skill 自身的默认值（This skill's own default）。 5-7 个阶段的区间、访谈次数、60% 信号覆盖率门槛、单一流失点规则、90 天重读周期。每一项都标注为“工作默认值，如果你的数据不支持可以调整”。
references/published-findings.md 保存了完整的分类体系：带有来源的有根据的主张、该 skill 自己设定的基线，以及应该直接拒绝的数字。在引用任何数字之前先阅读它。

Invocation examples

调用示例

The user saysWhat you do
"Map the developer journey for our API product"Full run, steps 1-7. Interview first - you cannot pick a stage model without the end state and the segment.
"Developers try it and never reach production. Where are we losing them?"Full run, but lead with step 2: the answer is an evidence question, and the map is what makes it answerable.
"Who owns each step of our developer experience?"Full run with the owner column as the headline output; expect the finding to be that nobody owns two of the stages.
"Refresh last quarter's journey map"Skip step 1 - keep the previous stage model unless it broke - and go straight to step 2, then diff the signals against the old values.
"Which of these five stages should we fix first?"Steps 2 and 6 only, on the stage list they already have. Do not re-cut their model.
Decline and route two kinds of request:
  • "Rewrite our quickstart so it converts better" - a one-stage fix does not need a seven-stage artefact. Route to the quickstart skill named at the end of this file.
  • "Build our developer metrics framework", "which segment should we target?" - upstream or downstream of the map, not part of it. Route to the metrics and segmentation skills named there too.
The deliverable is always a single markdown document with seven headings, shown in step 7:
  • one table
  • one buyer lane
  • three named moments
  • one leak
  • one handoff
  • one gap list
用户说你要做什么
“为我们的 API 产品绘制开发者旅程图”完整执行，步骤 1-7。先进行访谈 —— 没有最终状态和受众细分，你就无法选择阶段模型。
“开发者试用了产品却从未进入生产。我们在哪里流失了他们？”完整执行，但以步骤 2 开头：答案是一个证据问题，而地图使其成为可回答的问题。
“谁负责我们开发者体验的每一步？”完整执行，并将负责人列作为主要输出；预计会发现两个阶段无人负责。
“刷新上季度的旅程图”跳过步骤 1 —— 保留之前的阶段模型，除非它已失效 —— 直接进入步骤 2，然后将信号与旧值进行对比。
“这五个阶段中我们应该先修复哪一个？”仅执行步骤 2 和 6，基于他们已有的阶段列表。不要重新切分他们的模型。
拒绝并转介两类请求：
  • “重写我们的快速入门指南，使其转化更好”——单个阶段的修复不需要七个阶段的产物。转介至本文末尾列出的 quickstart skill。
  • “构建我们的开发者指标框架”“我们应该针对哪个细分受众？”——这些是地图的上游或下游，不属于地图本身。转介至同样列出的指标和细分 skill。
交付物始终是一份包含七个标题的 markdown 文档，见步骤 7：
  • 一个表格
  • 一条买家通道
  • 三个关键时刻
  • 一个流失点
  • 一次交接
  • 一份缺口清单

Interview

访谈

Ask one question at a time and offer options where you can. Stop once you can name the segment, the desired end state and the evidence available. Confirm the rest while drafting.
  1. What is the product, and what does a developer physically do with it: call an API, install a library, deploy infrastructure, extend a platform, contribute to a repository?
  2. Which single audience segment is this map for? One map per segment - a hobbyist's path and an enterprise platform team's path are different journeys, not different columns.
  3. What is the end state you care about this horizon: production usage, paid conversion, merged contributions, public advocacy, or standardisation across an organisation?
  4. In a purchase, is the developer the buyer, an influencer, or neither? Who signs, and at which point do they appear?
  5. Is the product self-serve, sales-assisted, free and open source, or a mix?
  6. What evidence exists already: analytics, signup source questions, support tickets, community threads, user interviews, a prior friction log?
  7. Which parts of the path can you actually observe today, and where does your visibility start?
  8. Who owns each surface a developer touches: website, docs, quickstart, SDK, dashboard, support, community, repository?
  9. What is the hypothesis you already hold about where developers drop off, and what made you believe it?
  10. Is this a first map, or a refresh of one that exists? If a refresh, what changed since?
  11. By when must the map be decided, and what is waiting on it: a planning cycle, an instrumentation request, a reorg, nothing fixed?
  12. Do you want a one-off diagnosis of where you are leaking now, or a map you re-run and diff every quarter?
  13. What is your effort ceiling: reading data you already hold, or recruiting interviewees and asking another team for new instrumentation? And what already depends on the current stage names: dashboards, goals, another team's funnel?
Those three set the ranking in step 1, so ask them before naming any model:
  • A near date deletes the models whose stage boundaries you cannot see in data you already hold.
  • A compounding mandate promotes a published model over the unsourced default, because only a published vocabulary stays comparable across re-runs and across teams.
  • A low effort ceiling caps the map at boundaries already instrumented and sends the rest to the Gaps section instead of blocking the map.
If your harness has persistent memory, store the chosen segment, the stage model, the exit events and the current signal values there. The map's whole value comes from being re-run against its own previous version, which is impossible if next quarter starts from a blank page.
每次只问一个问题，并在可能的情况下提供选项。一旦你能说出细分受众、期望的最终状态和可获得的证据，就停止提问。在起草时确认其余事项。
  1. 产品是什么，开发者实际用它做什么：调用 API、安装库、部署基础设施、扩展平台、向代码库贡献代码？
  2. 这张地图针对哪一个受众细分？每个细分一张地图——爱好者的路径和企业平台团队的路径是不同的旅程，而不是不同的列。
  3. 在这个阶段你最关心的最终状态是什么：生产使用、付费转化、合并的贡献、公开倡导，还是组织范围内的标准化？
  4. 在购买过程中，开发者是购买者、影响者，还是两者都不是？谁签字，他们在哪个节点出现？
  5. 产品是自助服务、销售辅助、免费开源，还是混合模式？
  6. 已经有哪些证据：分析、注册来源问题、支持工单、社区讨论、用户访谈、之前的摩擦日志？
  7. 你今天实际能观察到路径的哪些部分？你的可见性从哪里开始？
  8. 谁负责开发者接触的每个表面：网站、文档、快速入门、SDK、仪表盘、支持、社区、代码库？
  9. 你已经持有的关于开发者在何处流失的假设是什么？是什么让你相信这一点？
  10. 这是第一张地图，还是对现有地图的刷新？如果是刷新，自上次以来发生了什么变化？
  11. 地图必须在何时定稿？哪些事项在等待它：规划周期、埋点请求、重组、没有固定事项？
  12. 你想要一次性的流失诊断，还是一张每季度重新运行并对齐差异的地图？
  13. 你的工作量上限是什么：只读取已有数据，还是招募访谈对象并要求另一个团队进行新的埋点？当前阶段名称已经依赖了哪些东西：仪表盘、目标、另一个团队的漏斗？
这三个问题决定了步骤 1 中的排序，因此在命名任何模型之前先问它们：
  • 日期的临近会删除那些你在已有数据中看不到阶段边界的模型。
  • 可组合性会将公开模型提升到无来源默认值之上，因为只有公开的词汇才能在重复运行和跨团队之间保持可比性。
  • 较低的工作量上限会将地图限制在已经埋点的边界，并将其余部分放入“Gaps”部分，而不是阻碍地图。
如果你的 harness 有持久化记忆，请将选定的细分受众、阶段模型、退出事件和当前信号值存储在其中。地图的整个价值来自于与自己上一版本的对比重跑，如果下个季度从空白页开始，这是不可能的。

Step 1 - Choose the stage model, do not invent one

步骤 1 - 选择阶段模型，不要自己发明

Say you are in brainstorming mode and do not draft rows yet.
Two passes, in this order: delete first, then rank what survives.
  • Delete. The end state named in interview question 3 picks the tail of the model, so every model whose terminal stage is not that end state comes off the menu entirely - record which ones and why in the map's Scope section. Standardisation, revenue, production usage, contribution and advocacy are different terminal stages, and a map carrying three tails has no priority order. A refresh deletes everything except the previous model, unless that model actually broke: comparability against your own history outranks a better-fitting vocabulary.
  • Rank. Rank the survivors, and say the ranking out loud. Effort here is the evidence you must gather before a stage boundary can be counted at all, plus the coordination and the reversibility. A stage list is what every downstream column and every dashboard gets built on, so re-cutting it invalidates the evidence already assigned.
  • effort: Revell six-stage > AAARRRP > OSS contributor funnel > API five-stage arc > unsourced default
  • efficiency: API five-stage arc > OSS contributor funnel > AAARRRP > Revell six-stage > unsourced default
There is deliberately no value line. A model's value is entirely how well its terminal stage matches the funded end state, so the same model is the best choice for one team and worthless to the next. Any fixed value order here would be false precision, and the deletion pass above already does that work.
In orders of magnitude:
  • The API five-stage arc's boundaries - first call, integration, production - usually already sit in product telemetry: an hour to a week of reading.
  • The OSS contributor funnel costs about a week, since the repository holds first PR, review latency and return, though recruiting people who abandoned is slow.
  • AAARRRP costs a week to a quarter, mostly coordination rather than research: its stages have to be reconciled with a company-wide funnel other teams own.
  • Revell six-stage costs a quarter, because the standardisation boundary needs account rollup and buyer-side interviews almost nobody already has.
Note where the cheapest option lands: the unsourced default costs near-zero and still ranks last on efficiency, because it buys no comparability with the field's vocabulary or with any other team's funnel - cheap and efficient are not the same ordering.
The efficiency order starves Revell six-stage, the only model with an explicit standardisation stage. Promote it anyway when the funded question is why teams adopt but the organisation never standardises, or when a renewal depends on becoming an org-wide default - then the account rollup it forces is the point, not the cost.
Treat both lines as a default, not a law; they move with what a given team already instruments. Re-rank against that:
  • an existing company-wide AARRR funnel collapses AAARRRP's coordination cost and promotes it to first
  • account rollup already built for sales removes most of Revell's cost
  • a product with no telemetry before signup demotes the API arc, since its early boundaries are exactly the unobservable ones
Offer two or three candidate stage models drawn from references/stage-models.md, in efficiency order, each with what it makes visible, what it hides, and what its boundaries will cost you to observe. Recommend one and say why. Let the user choose before any row gets written.
Guidance that decides the rest:
  • Prefer five to seven stages - this skill's default band, not a standard. Fewer hides the leak inside a stage; more produces stages nobody can name an exit event for.
  • Split a stage only when it has two distinct exit events with different owners - "evaluation" splits cleanly when reading docs and running a local trial are owned by different teams.
  • Keep the model's published stage names when you use a published model, so the map stays comparable with the field's vocabulary and with the program strategy that pins goals to it.
说明你处于头脑风暴模式，尚未起草行。
两轮筛选，按此顺序：先删除，再对幸存者排序。
  • 删除。 访谈问题 3 中命名的最终状态决定了模型的尾部，因此所有终态不是该最终状态的模型都将被完全移出候选清单——在地图的 Scope 部分记录哪些以及为什么。标准化、收入、生产使用、贡献和倡导是不同的终态，携带有三个尾部的地图没有优先级顺序。刷新操作会删除除先前模型之外的所有模型，除非该模型确实失效：与自身历史可比性优于更合适的词汇。
  • 排序。 对幸存者进行排序，并大声说出排序结果。这里的成本是：在一个阶段边界能够被计数之前你必须收集的证据，以及协调和可逆性。阶段列表是所有下游列和所有仪表盘的构建基础，因此重新切分会使得已经分配的证据失效。
  • 成本: Revell 六阶段 > AAARRRP > OSS 贡献者漏斗 > API 五阶段弧 > 无来源默认值
  • 效率: API 五阶段弧 > OSS 贡献者漏斗 > AAARRRP > Revell 六阶段 > 无来源默认值
这里故意没有价值线。一个模型的价值完全取决于其终态与资助的最终状态的匹配程度，因此同一个模型对一个团队来说是最佳选择，对下一个团队则毫无价值。任何固定的价值顺序都是虚假的精确，上面的删除操作已经完成了这项工作。
按数量级来看：
  • API 五阶段弧的边界——首次调用、集成、生产——通常已经存在于产品遥测中：阅读一个小时到一周。
  • OSS 贡献者漏斗大约需要一周，因为代码库中保存了第一个 PR、审查延迟和返回情况，尽管招募放弃者是缓慢的。
  • AAARRRP 花费一周到一个季度，主要是协调而非研究：它的各个阶段必须与公司范围内其他团队拥有的漏斗进行协调。
  • Revell 六阶段花费一个季度，因为标准化边界需要账户汇总和几乎没有人已有的购买方访谈。
注意最便宜选项的位置：无来源默认值成本接近零，但效率仍排最后，因为它无法与领域词汇或任何其他团队的漏斗进行可比性——便宜和高效不是同一个排序。
效率排序使唯一的显式标准化阶段模型 Revell 六阶段被边缘化。当资助的问题确实 是 关于为什么团队采用但组织从未标准化时，或者当续约取决于成为组织范围的默认时，仍然应该提升它——那么它强制进行的账户汇总就是重点，而不是成本。
将这两条线视为默认值，而不是规律；它们会随着给定团队已经埋点的情况而变化。据此重新排序：
  • 现有公司范围的 AARRR 漏斗会消除 AAARRRP 的协调成本并将其提升到第一位
  • 为销售构建的账户汇总会消除 Revell 的大部分成本
  • 注册前没有遥测的产品会降低 API 弧的位置，因为它的早期边界恰恰是不可观察的
从 references/stage-models.md 中提供两到三个候选阶段模型，按效率排序，每个模型说明它使什么可见、隐藏了什么、以及观察其边界需要付出什么成本。推荐一个并说明原因。在写入任何行之前让用户选择。
决定其余部分的原则：
  • 偏好五到七个阶段——这是该 skill 的默认区间，而不是标准。更少的阶段会将流失隐藏在阶段内部；更多的阶段会产生没有人能命名退出事件的阶段。
  • 只有当某个阶段包含两个具有不同负责人的不同退出事件时才拆分它——当阅读文档和运行本地试用由不同团队负责时，“评估”就可以干净地拆分。
  • 使用公开模型时，保留模型的公开阶段名称，以使地图与领域词汇以及与之挂钩的项目策略保持可比性。

Step 2 - Collect evidence before filling any row

步骤 2 - 在填写任何行之前收集证据

A map assembled from opinion documents the team's beliefs, not the developer's path. Gather evidence first, cheapest source first, and tag each finding with the stage it belongs to.
  1. Walk the path yourself and keep a friction log (Google's DevRel practice; protocol in the reference below): one realistic scenario, a running record of what you searched, clicked, pasted and felt, with green/yellow/red marks. It is the only source that catches drop-offs nobody ever reports.
  2. Mine what developers already wrote - support tickets, issues, community questions, docs searches that returned nothing. Cluster them by stage; the biggest cluster is a friction candidate, not yet a conclusion.
  3. Interview five to eight developers who completed the journey, and - harder to recruit, worth more - three who abandoned it. Both counts are this skill's defaults; the 5-8 matches common usability-panel sizes, not a journey-mapping standard.
  4. Read the funnel data that already exists before asking for new instrumentation.
Check what each surface can physically report before promising a signal. Three corrections move a developer map's numbers more than anything else:
  • Analytics blocking. Plausible measured 58% of a tech audience blocking a third-party analytics script (82.3% on Linux, 88.3% on Firefox), in an August 2021 measurement on one site carrying Hacker News and Reddit traffic, read against Plausible's own proxied script. That makes it a single-site measurement by an interested vendor, but the only public one. Absolute traffic numbers on developer surfaces are therefore wrong by a factor that varies page by page; only ratios inside one source survive.
  • Retention windows. Repository traffic endpoints keep 14 days, npm downloads 18 months, PyPI series 180 days (GitHub REST Metrics/Traffic and pypistats docs). Snapshot any signal drawn from them from the day it is defined; expired data cannot be backfilled.
  • Referrer loss. Aggregators, chat clients, privacy browsers, and AI assistants strip referrers - roughly 70% of AI-assistant traffic arrives with none, a newsletter estimate (Demand Curve #331), not a study. A large "direct" bucket is the normal case, not an instrumentation bug.
references/evidence-and-signals.md lists what to look for per stage, the candidate signals, which team usually owns each surface, the friction-log and exit-interview protocols, and the full per-surface instrumentation reality.
仅凭观点拼接而成的地图记录的是团队的信念，而不是开发者的路径。先收集证据，先收集最便宜的证据，并将每个发现标记到所属阶段。
  1. 亲自走一遍路径，并记录摩擦日志（Google 的 DevRel 实践；协议见下面的参考）：一个真实场景，连续记录你搜索、点击、粘贴和感受的内容，并用绿/黄/红标记。这是唯一能捕捉到无人上报的流失的来源。
  2. 挖掘开发者已经写下的内容——支持工单、issue、社区问题、无结果的文档搜索。按阶段对它们进行聚类；最大的聚类是一个摩擦候选，还不是结论。
  3. 访谈五到八位完成了旅程的开发者，以及——更难招募但价值更高的——三位中途放弃的开发者。这两个数字都是该 skill 的默认值；5-8 与常见可用性小组规模一致，而不是一个旅程映射标准。
  4. 在要求新的埋点之前，先阅读已经存在的漏斗数据。
在承诺一个信号之前，检查每个表面在物理上能够报告什么。三项修正对开发者地图数字的影响最大：
  • 分析屏蔽（Analytics blocking）。 Plausible 在 2021 年 8 月对一个带有 Hacker News 和 Reddit 流量的网站进行的测量（相对于 Plausible 自己的代理脚本）发现，58% 的技术受众屏蔽了第三方分析脚本（Linux 上 82.3%，Firefox 上 88.3%）。这使得它成为感兴趣供应商进行的单站点测量，但也是唯一公开的测量。因此，开发者表面上的绝对流量数字会以一个逐页变化的因子出现偏差；只有单一来源内的比率是可靠的。
  • 保留窗口（Retention windows）。 代码库流量端点保留 14 天，npm 下载保留 18 个月，PyPI 系列保留 180 天（GitHub REST Metrics/Traffic 和 pypistats 文档）。在你定义信号的那一天就对从这些端点提取的任何信号进行快照；过期数据无法回填。
  • 引荐丢失（Referrer loss）。 聚合器、聊天客户端、隐私浏览器和 AI 助手会剥离引荐来源——大约 70% 的 AI 助手流量到达时没有引荐来源，这是一份新闻通讯的估计（Demand Curve #331），不是一项研究。一个很大的“直接访问”桶是正常情况，而不是埋点错误。
references/evidence-and-signals.md 列出了每个阶段要寻找的内容、候选信号、每个表面通常由哪个团队负责、摩擦日志和退出访谈协议，以及完整的每个表面的埋点现实。

Step 3 - Fill one row per stage

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

Each row carries eight fields. The three in bold are what separate this from a generic journey map; a row missing any of them is not finished.
FieldWhat goes in it
Stagethe name from the chosen model
Developer's jobwhat the person is trying to accomplish, in their words, not the vendor's funnel language
Entry triggerthe observable event that starts the stage
Exit eventthe single observable event proving they moved on - first successful API call, first deploy to production, first merged PR, first talk given
Touchpointsthe surfaces involved: docs page, repo, CLI output, dashboard, community thread, support ticket
Ownerone person or team accountable for this stage's exit rate
Friction evidencea cited observation with its source, never a hypothesis; write "no evidence yet" when there is none
Signalone metric with its data source and its current value, or 
not instrumented
Keep out two columns generic journey maps carry:
  • Emotion scores get invented at developer volumes and crowd out the accountable columns.
  • Opportunity lists written in the same pass turn the map into a backlog before anyone knows which stage leaks.
Mark every stage whose numbers are inferred rather than measured - with the blocking and referrer loss from step 2, the early stages almost always are. An honest 
inferred
label protects the map's later conclusions; a confident fake number destroys them.
每一行包含八个字段。加粗的三个是将其与普通旅程地图区分开来的关键；缺少任何一个字段的行都是不完整的。
字段内容
阶段所选模型的名称
开发者的任务这个人试图完成什么，用他们的话说，而不是供应商的漏斗语言
进入触发启动该阶段的可观察事件
退出事件证明他们继续前进的单一可观察事件 - 第一次成功的 API 调用、第一次生产部署、第一个合并的 PR、第一次演讲
接触点涉及的表面：文档页面、代码库、CLI 输出、仪表盘、社区讨论、支持工单
负责人对该阶段退出率负有责任的一人或团队
摩擦证据带有来源的引用观察，绝不是假设；没有时写“尚无证据”
信号一个指标及其数据来源和当前值，或 
not instrumented
省略普通旅程地图中常有的两列：
  • 情绪分数在开发者规模下是编造出来的，并且会挤掉负责人列。
  • 在同一轮中写下的机会清单会在任何人知道哪个阶段流失之前把地图变成待办事项列表。
标记每一个数字是推断而非测量的阶段——考虑到步骤 2 中的屏蔽和引荐丢失，早期阶段几乎总是如此。诚实的 
inferred
标签保护地图后续的结论；自信的虚假数字会摧毁它们。

Step 4 - Add the buyer lane, or say there isn't one

步骤 4 - 添加买家通道，或说明没有

  • B2B, developer is not the buyer. Add a second, shorter lane for the economic buyer - security review, legal and licensing, procurement, budget approval - joining at commitment or standardisation. It gets its own exit events (security questionnaire cleared, contract signed) and its own owner, usually outside DevRel entirely. The developer's lane continues in parallel: a champion who cannot arm an approver stalls at a stage the developer lane cannot show.
  • Roll usage up to accounts before reading this lane. The developer lane counts people; the buyer lane counts organisations. Group signups by email domain, workspace or licence first - forty signups from one company look like forty leads until you do.
  • Read three signal families, in increasing order of buying intent:
    • Depth - production use, sustained volume, wired into CI.
    • Spread - a second and third developer in the same account.
    • Boundary contact - someone opened an SSO or RBAC page, asked a compliance question, hit a seat limit, requested a security questionnaire.
    Boundary contact is rarest, strongest, and the cleanest exit event the lane can have - instrument it first.
  • Individual adoption or B2C-style self-serve. The two lanes collapse; the developer decides and pays, or nothing is paid at all. State this explicitly on the map rather than leaving an empty buyer lane, so a later reader knows it was decided, not forgotten.
  • Open source with no purchase. There is no buyer lane, but there is often an adoption-approval step inside the user's own company (license compatibility, dependency policy). Model it as friction in the adoption stage, not as a lane.
Everything else in the map works the same for both - the stage model, evidence gathering, exit events and leak diagnosis do not change with the business model.
  • B2B，开发者不是购买者。 为经济买家添加第二条较短的通道——安全审查、法律与许可、采购、预算批准——在承诺或标准化时加入。它有自己的退出事件（安全问卷通过、合同签署）和它自己的负责人，通常完全在 DevRel 之外。开发者通道并行继续：一个无法为审批者提供充分理由的倡导者，会在开发者通道看不到的某个阶段停滞。
  • 在阅读这条通道之前，先将使用量汇总到账户。 开发者通道统计个人；买家通道统计组织。首先按邮箱域名、工作区或许可证对注册进行分组——一家公司的 40 个注册看起来像 40 个线索，直到你这样做。
  • 按照购买意图递增的顺序读取三个信号系列：
    • 深度（Depth） - 生产使用、持续量、接入 CI。
    • 扩展（Spread） - 同一账户中的第二和第三个开发者。
    • 边界接触（Boundary contact） - 有人打开了 SSO 或 RBAC 页面、提出了合规问题、达到了席位限制、请求了安全问卷。
    • 边界接触是最稀有、最强、也是通道可以拥有的最干净的退出事件——先对它进行埋点。
  • 个人采用或 B2C 风格的自助服务。 两条通道合并；开发者决定并付费，或者根本不需要付费。在地图上明确说明这一点，而不是留下空的购买者通道，以便后续读者知道这是经过决定的，而不是被遗忘的。
  • 无购买的开源。 没有买家通道，但在用户所在公司内部通常有一个采用批准步骤（许可证兼容性、依赖策略）。将其建模为采用阶段的摩擦，而不是一条通道。
地图中的所有其他内容对两者都同样适用——阶段模型、证据收集、退出事件和流失诊断不会随着商业模式而改变。

Step 5 - Name the three critical moments

步骤 5 - 命名三个关键时刻

Pull these out of the rows and state them separately; they are what the map gets read for.
  • First success - the moment the developer gets a real result from the product. Name it concretely and note how long it takes today.
  • Moment of truth - the point where they commit or walk: the decision to put it in a real project, to recommend it, to open a PR.
  • Abandonment point - where the evidence says most people actually stop, which is often earlier and duller than the team assumes.
从行中提取它们并单独说明；这些正是地图被阅读的原因。
  • 首次成功（First success） - 开发者从产品中获得真正成果的时刻。具体地命名它，并记录当前需要多长时间。
  • 关键时刻（Moment of truth） - 他们决定投入或离开的节点：决定将其放入真实项目中、推荐它、打开 PR。
  • 放弃点（Abandonment point） - 证据表明大多数人实际停下的地方，这通常比团队假设的更早、更不起眼。

Step 6 - Diagnose the leak

步骤 6 - 诊断流失

  • Compute stage-to-stage conversion only where both exit events are counted. Leave the rest labelled 
    inferred
    .
  • Pick one stage to work on: the earliest stage that both converts poorly and has an owner able to change it. Earliest wins because every downstream fix is diluted by the losses above it; owned wins because an unowned recommendation is a wish. Rank the candidates by developers recovered per unit of fix effort - a docs fix and a re-architected onboarding do not cost the same week - and only then apply earliest-and-owned as the tiebreak.
  • Say what that ordering starves. A late stage with a huge payoff and a heavy fix - standardisation, advocacy, contribution - never wins a round against an early cheap one, so a team re-running this map every quarter can spend years never touching it. Promote it when the earliest leaking stage is unowned, when its fix is already in flight, or when the end state from the interview is that late stage.
  • Below roughly 30 events in a period, publish the raw list with dates instead of a rate - a statistical convention, not a DevRel finding, and later journey stages hit that floor constantly.
  • Compare only against this map's own previous version. Another company's published funnel has a different audience, product maturity and definition of every stage.
  • If most rows name DevRel as owner, report that as a finding about the organisation. It means the surfaces have no accountable owner, which is a bigger problem than the leak.
Only after the stage is chosen, say why it leaks, using BJ Fogg's behaviour model (B = MAP: a behaviour happens when motivation, ability and a prompt converge). B=MAP explains one stage; it cannot rank stages against each other.
Reach for it before choosing and you will write a fluent motivation story about a stage that was never the binding constraint. A leaking stage is a behaviour that is not happening, and the model splits the cause three ways, each landing on a different owner:
  • Ability too low - the step is too long, needs an undeclared prerequisite, or asks for an unfamiliar routine. Fixed by docs, developer experience or product. This is the default answer for a developer audience, and Fogg's own directional advice applies: raise ability rather than pump motivation, because, in his words, "motivation is unreliable. Luckily, ability is not."
  • Motivation too low - nothing at this stage showed a reason worth the effort. Fixed by positioning and product marketing. A motivation-first fix on a developer stage usually means the team preferred writing copy to removing steps.
  • Prompt missing - they could and would have continued, and nothing told them to. Fixed by in-app guidance, lifecycle content or community.
  • 仅在两个退出事件都被统计的情况下计算阶段间转化率。将其余部分标记为 
    inferred
    。
  • 选择一个要处理的阶段：最早出现的、既转化不佳又有能够改变它的负责人的阶段。最早出现者胜出，因为下游的每一个修复都会被上游的流失所稀释；有负责人者胜出，因为没有负责人的建议只是一个愿望。按每单位修复成本所挽回的开发者数量对候选进行排序——文档修复和重新架构的上手流程并不花费相同的一周——然后才将最早且有负责人作为平局决胜。
  • 说明这种排序会边缘化什么。一个具有巨大回报但修复沉重的后期阶段——标准化、倡导、贡献——在与早期低成本阶段的对决中永远不会赢，因此每季度重新运行这张地图的团队可能多年都不会触及它。当最早的流失阶段没有负责人、当它的修复已经在进行中、或者当访谈中的最终状态确实就是那个后期阶段时，提升它。
  • 在一个周期内事件大约少于 30 个时，发布带有日期的原始计数，而不是比率——这是一个统计惯例，不是 DevRel 发现，而后期的旅程阶段经常触及这个下限。
  • 只与这张地图自己的上一版本进行比较。另一家公司的公开漏斗有不同的受众、产品成熟度和每个阶段的定义。
  • 如果大多数行将 DevRel 列为负责人，将其作为关于组织的发现进行报告。这意味着这些表面并没有一个真正负责任的负责人，这比流失问题更严重。
只有在阶段被选择之后，才使用 BJ Fogg 的行为模型（B = MAP：当动机、能力和提示同时具备时，行为才会发生）来解释它 为什么 流失。B=MAP 可以解释一个阶段；它不能对阶段进行相互排序。
在选择之前就使用它，你会写出一段流畅的动机故事，关于一个从来都不是约束条件的阶段。一个流失的阶段是一种没有发生的行为，该模型将原因分为三类，每类落在不同的负责人身上：
  • 能力太低 - 步骤太长，需要一个未声明的先决条件，或者要求一个不熟悉的流程。通过文档、开发者体验或产品来修复。这是开发者受众的默认答案，Fogg 自己的方向性建议也适用：提高能力而不是激发动机，因为用他的话来说，“动机不可靠。幸运的是，能力不是这样。”
  • 动机太低 - 这个阶段没有任何东西显示出值得付出努力的理由。通过定位和产品营销来修复。对开发者阶段采取动机优先的修复通常意味着团队更愿意写文案而不是移除步骤。
  • 缺少提示 - 他们本可以继续并且也愿意继续，但没有任何东西提示他们。通过应用内引导、生命周期内容或社区来修复。

Step 7 - Write the map and validate it section by section

步骤 7 - 编写地图并逐节验证

markdown
undefined
markdown
undefined

Developer journey map - <segment>, <date>

Developer journey map - <segment>, <date>

Scope segment, end state, stage model used and why

Scope segment, end state, stage model used and why

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

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

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

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

Moments first success, moment of truth, abandonment point

Moments first success, moment of truth, abandonment point

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

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

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

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

Gaps stages marked inferred, and what would make them measurable

Gaps stages marked inferred, and what would make them measurable


Present one section at a time and get agreement before writing the next. A wrong stage model caught at the first heading costs a paragraph; caught at the leak diagnosis it costs the whole document.

A worked map with weak and strong versions of the same rows is in [references/journey-map-example.md](./references/journey-map-example.md).

一次展示一个部分，并在编写下一部分之前获得同意。在第一个标题处发现错误的阶段模型只需要一段话的代价；在流失诊断时发现则要付出整个文档的代价。

包含相同行的弱版本和强版本的完整示例地图见 [references/journey-map-example.md](./references/journey-map-example.md)。

Quality gate

质量门槛

Hold the map to this threshold and iterate until it passes, then report the check explicitly. These are this skill's own baselines, not an industry standard. Say so if a user asks where a number comes from, and let them move one when their situation argues for it.
  • Every stage has exactly one exit event, phrased as an observable event rather than a state of mind.
  • Every stage names one owner, and at least one owner sits outside the DevRel team.
  • At least 60% of stages carry a signal with a real current value; the rest say 
    not instrumented
    and appear in the Gaps section.
  • Every friction claim cites its source; no row mixes evidence with hypothesis.
  • Exactly one leak is nominated, with a named owner and a re-read date.
  • Inferred stages are labelled as inferred, everywhere they appear.
  • The map fits on one page at readable size - if it does not, the stage list is too long or the cells are carrying prose.
A map failing the signal line is not blocked. Ship it with the gaps named; an honest map with holes beats a complete map with invented numbers, and the gaps become the instrumentation request.
将地图保持在以下阈值内，并反复迭代直到通过，然后明确报告检查结果。这些是该 skill 自己的基线，不是行业标准。如果用户问数字来自哪里，请如实说明，并允许他们在其情况支持时进行调整。
  • 每个阶段恰好有一个退出事件，并以可观察事件而非心理状态来表述。
  • 每个阶段指定一个负责人，并且至少有一个负责人来自 DevRel 团队之外。
  • 至少 60% 的阶段带有具有真实当前值的信号；其余阶段标注 
    not instrumented
    并出现在 Gaps 部分。
  • 每项摩擦声明都注明来源；没有一行将证据与假设混在一起。
  • 恰好指定一个流失点，并带有指定的负责人和重读日期。
  • 推断阶段在所有出现的地方都标记为 inferred。
  • 地图以可读的大小适合一页——如果不能，说明阶段列表太长或单元格承载了散文。
未通过信号线的地图不会被阻止。带着已命名的缺口发布它；一张有缺口的诚实地图，胜过一张用编造数字填充的完整地图，而且这些缺口会变成埋点请求。

Common failure modes

常见失败模式

  • Mapping the funnel the company wishes for. Stage names taken from the sales pipeline describe internal process, not developer behaviour. Test each stage name against "would a developer recognise this as something they did?".
  • One map for all developers. A hobbyist, a platform engineer and an enterprise architect share almost no friction. Pick a segment or produce nothing.
  • Exit events that are not events. "Understands the value proposition" cannot be observed, counted or owned. "Ran the quickstart to completion" can.
  • Filling the whole map from analytics. Analytics starts after signup, which is already mid-journey. Everything before it needs qualitative evidence or an honest 
    inferred
    .
  • Assuming silence means satisfaction. Developers who fail at setup rarely file anything; they leave. Absence of complaints about a stage is not evidence the stage works.
  • Nominating three leaks. Three priorities is none. Rank them and fix the earliest owned one.
  • Skipping the buyer lane in B2B. The map then shows a healthy developer journey next to a stalled pipeline and explains neither.
  • Treating the map as permanent. Re-read it when a launch, a pricing change, a docs rewrite or a new SDK moves a surface. A map older than two quarters describes a product that no longer exists.
  • Borrowing another company's conversion rates. The numbers in circulation are single-company anecdotes with incompatible stage definitions. Quoting one gives the map false confidence and hides the only comparison that means anything - against its own last version.
  • Writing absolute traffic numbers into early stages. The blocking rates from step 2 make any session count a fraction that varies page by page. Keep ratios inside one source, and label the stage inferred.
  • 映射公司希望拥有的漏斗。 从销售管道中取用的阶段名称描述的是内部流程，而不是开发者行为。用“开发者会不会认为这是他们做过的事情？”来测试每个阶段名称。
  • 为所有开发者绘制一张地图。 爱好者、平台工程师和企业架构师几乎没有任何共同的摩擦。选择一个细分受众，否则什么都不产出。
  • 不是事件的退出事件。 “理解价值主张”无法被观察、计数或负责。“将快速入门完整运行”则可以。
  • 完全从分析中填充地图。 分析开始于注册之后，这已经是旅程的中段。在此之前的一切都需要定性证据或诚实的 
    inferred
    。
  • 假设沉默意味着满意。 在设置阶段失败的开发者很少提交任何东西；他们直接离开。对某个阶段没有投诉并不是该阶段有效的证据。
  • 提名三个流失点。 三个优先级等于没有优先级。对它们进行排序并修复最早的且有负责人的一个。
  • 在 B2B 中跳过买家通道。 地图随后会显示一个健康的开发者旅程，旁边是一个停滞的管道，但两者都无法解释。
  • 将地图视为永久性的。 当发布、定价变更、文档重写或新 SDK 改变了某个表面时，重新阅读它。超过两个季度的地图描述的是一个不再存在的产品。
  • 借用其他公司的转化率。 流传的数字是单一公司的轶事，且阶段定义不兼容。引用这些数字会给地图带来虚假的信心，并隐藏唯一有意义的比较——与它自己上一版本的比较。
  • 将绝对流量数字写入早期阶段。 步骤 2 中的屏蔽率使得任何会话计数都是一个逐页变化的比例。保持单一来源内的比率，并标记该阶段为 inferred。

References

参考

  • references/stage-models.md - the published stage models, their sources, and how to pick one.
  • references/evidence-and-signals.md - evidence sources, candidate signals and typical owner per stage, the buyer-lane signal families, the per-surface instrumentation reality, and the friction-log and exit-interview protocols.
  • references/published-findings.md - which claims are sourced, which numbers are this skill's own baselines, and the figures to refuse.
  • references/journey-map-example.md - a full worked map with weak vs strong rows.
  • samber/developer-relations-skills@developer-segmentation - chooses the segment a map is drawn for.
  • samber/developer-relations-skills@devrel-metrics - turns the per-stage signals into a full measurement framework.
  • samber/developer-relations-skills@devrel-analytics - instruments per-stage signals.
  • samber/developer-relations-skills@devrel-strategy - pins program goals to the journey this map produces.
  • samber/developer-relations-skills@developer-quickstart-guide - stage-level fix for first success.
  • samber/developer-relations-skills@developer-docs-structure-audit - stage-level fix for evaluation and adoption friction.
  • references/stage-models.md - 公开的阶段模型、它们的来源，以及如何选择一个。
  • references/evidence-and-signals.md - 证据来源、候选信号和每个阶段的典型负责人、买家通道信号系列、每个表面的埋点现实，以及摩擦日志和退出访谈协议。
  • references/published-findings.md - 哪些主张有来源，哪些数字是该 skill 自身的基线，以及要拒绝的数字。
  • 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 - 针对评估和采用摩擦的阶段级修复。