samber/developer-relations-skills包含需要注意的行为
SKILL DETAIL
developer-journey-map
samber/developer-relations-skills/developer-journey-map
Maps the developer journey for one audience segment - discovery, trial, adoption, contribution, advocacy - as a stage-by-stage table where each stage carries an exit event, a named owner, cited friction evidence and one signal, and names the single leak worth fixing next. Use whenever someone asks what their developer journey looks like, wants a developer adoption funnel or journey map, asks why developers try the product but never reach production, where adoption drops off, who owns each step of developer experience, or how developers become contributors - even if they only say "we lose people somewhere". Not the metrics framework - use samber/developer-relations-skills@devrel-metrics.
安装量 · 409查看来源
Installation
npx skills add https://github.com/samber/developer-relations-skills --skill developer-journey-map
技能文件
SKILL.md
最近同步 · 2026年10月23日
evals/evals.json›
{
"skill_name": "developer-journey-map",
"evals": [
{
"id": 1,
"prompt": "I'm head of DevRel at Tarnhelm, we sell a hosted feature-flag platform to engineering orgs. The board question for FY27 is why five of our top ten accounts have 200+ developers on the platform but flags are still 'that team's tool' instead of the company standard - renewals at two of those accounts are pinned to us becoming the org-wide default. Sales ops already built full account rollup in our CRM, and product telemetry covers SDK init and first flag evaluation. Our internal wiki has a diagram someone drew in 2024 going discover -> try -> adopt -> contribute -> advocate. Can you put together a proper developer journey map for us? Segment is platform engineers at 1000+ person companies, and I need it before planning closes in three weeks.",
"expected_output": "A stage-model selection pass that names standardisation as the funded end state, deletes the models whose terminal stage is not standardisation, recommends Revell's six-stage model while explaining that the pre-built account rollup cancels most of its usual cost, and stops for the user's choice before any row is written.",
"files": [],
"expectations": [
"Names the funded end state as organisation-wide standardisation before proposing any stage model.",
"Deletes candidate stage models whose terminal stage is not standardisation, rather than ranking all of them.",
"Records which models were deleted and why in the map's Scope section.",
"Recommends Revell's six-stage model.",
"Lists Revell's stages: initial awareness, deep awareness, evaluation and validation, commitment, standardization, community and advocacy.",
"Attributes the six-stage model to Matthew Revell, developerrelations.com, 2016.",
"States that Revell's is the only published model carrying an explicit standardisation stage.",
"Notes Revell normally costs on the order of a quarter, because its standardisation boundary needs account rollup and buyer-side interviews.",
"Explicitly re-ranks Revell upward because Tarnhelm already has account rollup built for sales, which removes most of that cost.",
"Offers two or three candidate models with what each makes visible and what it hides, and asks the user to choose before writing rows.",
"Does not blend the existing discover -> try -> adopt -> contribute -> advocate spine with a published model.",
"Identifies discover -> try -> adopt -> contribute -> advocate as an unsourced default rather than a published framework.",
"Does not produce filled stage rows before the stage model is agreed."
]
},
{
"id": 2,
"prompt": "Quick sanity check before I take this to our VP of Product. Northwind Streams sells a managed Kafka alternative. Last quarter 28% of people who started our quickstart made a first successful produce-and-consume call, and 22% of signups hit what we internally call activation (a topic created plus one message consumed within 7 days). I keep seeing 40-60% quoted as the normal quickstart conversion for API products, and 20-40% as the standard self-serve activation rate, so on both counts we look broken. I want the journey map to open with those two gaps so the VP immediately sees the size of the problem. Segment is backend engineers at Series-A to Series-C startups, end state is production usage.",
"expected_output": "A refusal to benchmark 28% and 22% against the quoted figures, an explanation that circulating per-stage rates are incompatible single-company anecdotes, a correct account of what the real published activation numbers are and are not, and a map that carries Northwind's own rates with their definitions.",
"files": [],
"expectations": [
"Refuses to use the 40-60% quickstart conversion figure as a benchmark.",
"Refuses to use the 20-40% self-serve activation figure as a benchmark.",
"States that circulating per-stage conversion figures are single-company anecdotes with incompatible stage definitions.",
"States that no normal discovery-to-production rate for a developer product can be quoted.",
"States that the only honest comparison is against this same map's own previous version.",
"Does not open the map with a benchmark-gap framing.",
"Notes that the leading developer-tools product benchmark survey declines to publish a single activation-rate figure, because the activation milestone differs by product.",
"Names a real published activation figure with its methodology when discussing activation at all, for example the self-reported 25% median / 34% average survey band, and labels it self-reported.",
"Distinguishes that self-reported activation band from instrumented day-7 return figures (about 2.1% median, 7% top quartile) as different metrics under different definitions.",
"States that the popular round 20-40% figure collapses two different metrics into one number.",
"Records 28% and 22% in the map as Northwind's own numbers, with their definitions stated.",
"States that Northwind's activation definition (topic created plus one message consumed in 7 days) is product-specific and not comparable to another company's milestone.",
"Does not declare either stage broken on the strength of a borrowed rate."
]
},
{
"id": 3,
"prompt": "We're mapping the journey for Cindershell, a CLI-first infrastructure tool. Segment is SREs at mid-market companies, end state is production usage. I pulled Google Analytics for our docs site: 14,200 sessions last month, and 61% of them show as 'direct'. Our agency says a direct share that big means the tracking is broken and wants a six-week instrumentation project before we do anything else with the funnel. I'd like the awareness and evaluation rows of the map to carry those session numbers so we have something concrete at the top.",
"expected_output": "A map that refuses to write absolute docs traffic into cells, explains analytics blocking and referrer loss with their sources and caveats, labels the early stages inferred, and proceeds now with the instrumentation need recorded in Gaps rather than blocking on a six-week project.",
"files": [],
"expectations": [
"Declines to write the 14,200 absolute session count into any stage cell.",
"Cites the measurement that 58% of a tech audience blocks third-party analytics scripts.",
"Attributes that figure to Plausible Analytics' August 2021 measurement, and notes it is a single-site measurement by an interested vendor.",
"Gives at least one sub-breakdown from that measurement: 82.3% on Linux, 88.3% on Firefox, or 68.2% desktop versus 49.9% mobile.",
"States that the blocking rate varies page by page, so absolute developer-surface traffic is wrong by a factor that changes per page.",
"States that only ratios inside a single source survive.",
"States that a large 'direct' bucket is the normal case for a developer audience, not an instrumentation bug.",
"Notes roughly 70% of AI-assistant-driven traffic arrives with no referrer, and labels that as a newsletter estimate rather than a study.",
"Labels the awareness and evaluation stages as inferred wherever they appear in the map.",
"Declines to block the map on the six-week instrumentation project.",
"Puts the instrumentation need in the map's Gaps section.",
"Orders any proposed instrumentation fixes by cost: first-party or proxied script, then server or CDN log analysis, then a product-side event for anything past signup.",
"Does not recommend chasing the direct bucket down to a smaller share."
]
},
{
"id": 4,
"prompt": "Building the journey map for Orrery - an open-source Python data-quality library plus a paid cloud. Segment is data engineers, end state is production usage of the cloud. For the discovery and evaluation rows I want a year-over-year view: GitHub clones and unique visitors for the last 12 months. I also want our npm downloads (we ship a small JS companion) put next to our PyPI downloads so we can show which ecosystem is adopting us faster. And our all-time download counter just crossed 4.1M, which I'd like as the headline discovery signal.",
"expected_output": "A correction that repository traffic data expired long ago and cannot be backfilled, the retention windows for each registry, why npm and PyPI counts are not comparable and are not people, a rejection of the all-time counter, and the missing baseline recorded in Gaps.",
"files": [],
"expectations": [
"States that repository traffic endpoints retain only 14 days of data.",
"Notes those endpoints require write access to the repository.",
"States that expired repository traffic data cannot be backfilled, so a 12-month view is not available.",
"Instructs snapshotting any signal drawn from an expiring source into the team's own store from the day the signal is defined.",
"States npm download data retains 18 months.",
"States PyPI time series retain 180 days.",
"States npm counts HTTP 200 responses for tarballs, including build servers and mirrors, making it a request count rather than a person count.",
"States PyPI excludes known mirrors by default.",
"Concludes npm and PyPI download counts are not comparable to each other, and that neither is a user count.",
"Declines to present the requested year-over-year repository traffic comparison as achievable from existing data.",
"Rejects the 4.1M all-time download counter as a signal because it is monotonic and cannot fall when the journey breaks.",
"Proposes a rate or a period delta in place of the all-time counter.",
"Places the missing historical baseline in the map's Gaps section."
]
},
{
"id": 5,
"prompt": "Mapping the journey for Pallasgate, an authorization-as-a-service API. 340 signups last quarter on the free tier, 9 closed deals. The developer is definitely not the one signing - our deals go through a security review and then procurement, averaging about three months. Segment is backend engineers at 500-5000 person companies, end state is paid conversion. Right now our funnel view is just 340 signups flowing to 9 deals, which makes the conversion look catastrophic and I get asked about it every board meeting. Give me the journey map.",
"expected_output": "A two-lane map: the developer lane plus a separate buyer lane with its own exit events and owners, gated on rolling usage up to accounts first, with the depth/spread/boundary-contact families named in intent order and boundary contact instrumented first.",
"files": [],
"expectations": [
"Adds a second, shorter buyer lane alongside the developer lane rather than one merged funnel.",
"States that the developer lane counts people while the buyer lane counts organisations or accounts.",
"Requires usage to be rolled up to accounts before the buyer lane can be read at all.",
"Names at least one concrete rollup key: email domain, workspace or organisation object, licence or API key, or self-reported company.",
"States explicitly that the raw 340-to-9 comparison is unreadable without that rollup, because many signups from one company read as many leads.",
"Names the three buyer-lane signal families in increasing order of buying intent: depth, then spread, then boundary contact.",
"Defines spread as a second and third active developer inside the same account.",
"Gives at least two concrete boundary-contact examples, such as an SSO or RBAC page view, a compliance or audit question, a seat or rate limit hit, a security questionnaire request, or an enterprise terms page view.",
"Recommends instrumenting boundary contact first, and states it is the rarest and strongest of the three.",
"Gives the buyer lane its own exit events, such as security questionnaire cleared and contract signed.",
"Assigns the buyer lane's stages owners outside DevRel.",
"States the developer lane continues in parallel rather than ending where the buyer lane begins.",
"Records the champion as a participant carrying a specific artefact, not as a persona note."
]
},
{
"id": 6,
"prompt": "Here is our stage table for Quillbore, a GraphQL gateway. Segment is backend engineers at scale-ups, end state is production usage. Stages are awareness -> onboarding -> integration -> production -> advocacy.\n\n- Awareness: no owner, not instrumented\n- Onboarding: 47% of quickstart starters reach first success, owned by our docs team\n- Integration: 61% of first-success users call us from a service repo within 30 days, owned by product\n- Production: 58% of integrating accounts reach 14-day sustained traffic, owned by product\n- Advocacy: 3% of production accounts ever mention us publicly, owned by me (DevRel)\n\nAdvocacy is obviously our worst number by miles. I want the top three things to fix next quarter, and my read is that developers just aren't motivated enough to talk about us, so I'd like a motivation and incentive strategy for that stage.",
"expected_output": "Exactly one nominated leak - onboarding, not advocacy - chosen by recovered developers per unit of fix effort with earliest-and-owned as tiebreak, what that ordering starves and when advocacy gets promoted, and B=MAP applied only afterwards, to the chosen stage, with ability as the default branch.",
"files": [],
"expectations": [
"Nominates exactly one leak, not three.",
"Nominates onboarding rather than advocacy.",
"States that the earliest leaking stage with an owner able to change it wins, because every downstream fix is diluted by the losses above it.",
"Ranks the candidate stages by developers recovered per unit of fix effort before applying the earliest-and-owned tiebreak.",
"Explicitly names what that ordering starves: a late stage with a large payoff and a heavy fix, here advocacy.",
"States the conditions that would promote advocacy anyway: the earliest leaking stage being unowned, its fix already in flight, or advocacy being the funded end state.",
"Does not apply B=MAP or any motivation analysis before the leak stage is chosen.",
"Applies B=MAP only to the chosen stage, naming motivation, ability and prompt.",
"Attributes B=MAP to BJ Fogg.",
"States that B=MAP explains one stage and cannot rank stages against each other.",
"Declines to deliver a motivation or incentive strategy for advocacy.",
"Names ability as the default branch for a developer audience and directs effort at raising ability rather than pumping motivation.",
"Flags that the awareness stage has no owner as a finding in its own right."
]
},
{
"id": 7,
"prompt": "Our CX team has a journey map template they use for our consumer app and they want us to reuse it for the developer side of Gravelock, a self-hosted observability agent. Segment is platform engineers, end state is production usage. Their template has columns for stage, customer goal, emotion score out of 10, pain points, and opportunities. The stage names they drafted for us are: developer becomes aware of need, developer understands the value proposition, developer feels confident in the product, developer commits, developer champions. Can you fill it in?",
"expected_output": "A rewritten row format with the eight required fields, emotion scores and the opportunities column refused with reasons, and every unobservable stage name converted into an observable event.",
"files": [],
"expectations": [
"Refuses to include an emotion score column.",
"Gives the reason: emotion scores get invented at developer volumes and crowd out the columns carrying accountability.",
"Refuses to fill an opportunities column in the same pass as the map.",
"Gives the reason: writing opportunities in the same pass turns the map into a backlog before anyone knows which stage leaks.",
"Rejects 'developer understands the value proposition' as an exit event because it cannot be observed, counted or owned.",
"Rejects 'developer feels confident in the product' on the same grounds.",
"Replaces each unobservable stage name or exit criterion with a concrete observable event.",
"Names the eight fields a row carries: stage, developer's job, entry trigger, exit event, touchpoints, owner, friction evidence, signal.",
"Identifies exit event, owner and signal as the three fields without which a row is not finished.",
"Requires exactly one exit event per stage.",
"Requires exactly one signal per stage.",
"Writes the developer's job in the developer's own words rather than vendor funnel language.",
"Applies the test 'would a developer recognise this as something they did?' to each stage name."
]
},
{
"id": 8,
"prompt": "I maintain Thistlewrap, an MIT-licensed Go library for schema migrations, about 3,800 stars, used in production at a bunch of companies. I get maybe two outside PRs a quarter and almost every first-timer never comes back. I want a journey map that ends with people sticking around as contributors. Two side questions: I've been labelling issues 'easy' / 'medium' / 'hard' to help newcomers pick, and I'm not sure whether the map needs a buyer lane - companies run it in production but nobody pays us anything.",
"expected_output": "A map on the OSS contributor funnel with the merge as the contribution exit event, review latency as its signal, issue labels re-cut by API domain, and no buyer lane - with the adopting company's internal approval modelled as adoption-stage friction instead.",
"files": [],
"expectations": [
"Selects the OSS contributor funnel as the stage model, because the funded end state is sustained contribution.",
"Names its stages: land, find work, set up, change, submit, survive review, return.",
"Identifies local setup and waiting for review as the two steps that leak hardest and most silently.",
"Sets the contribution stage's exit event as the merge, not the pull-request submission.",
"Cites the finding that contributors who received code review within 48 hours returned and contributed again at a much higher rate.",
"Attributes that finding to GitHub's Open Source Guides.",
"Proposes time-to-first-review as the contribution stage's signal.",
"Cites that it only takes one negative experience to make someone not want to come back.",
"States that newcomers pick tasks by the API domain a task requires rather than by a maintainer's difficulty label.",
"Attributes that finding to the newcomer-barriers study of 74 participants.",
"Recommends re-labelling issues by API domain or area rather than easy/medium/hard.",
"States there is no buyer lane on a project with no purchase, and says so explicitly on the map rather than leaving the lane blank.",
"Models the adopting company's internal approval - licence compatibility, dependency policy - as friction inside the adoption stage rather than as a lane."
]
},
{
"id": 9,
"prompt": "We did a journey map for Vaneworth last quarter, a CI runner service, using the five-stage API arc: awareness, onboarding, integration, production, advocacy. It was drawn for our 'indie and small team' segment. Three things for this refresh. One: update the numbers - onboarding went 34% to 39%, integration 52% to 49%, production 28% to 31%. Two: fold our enterprise platform-team audience into it so we have one map for everyone instead of maintaining two. Three: marketing standardised on AARRR company-wide this quarter, so switch us to AAARRRP so the vocabularies line up.",
"expected_output": "A refusal to merge the two segments, the five-stage arc kept for continuity over the AAARRRP switch, and a refresh that skips model selection and diffs each signal against its previous value.",
"files": [],
"expectations": [
"Refuses to fold two audience segments into one map.",
"States the reason: a small-team path and an enterprise platform team's path are different journeys, so one map per segment.",
"Offers a second, separate map for the enterprise platform-team segment instead.",
"Keeps the five-stage API arc for this refresh rather than switching to AAARRRP.",
"States that on a refresh, comparability against the map's own history outranks a better-fitting vocabulary, and the model changes only if it actually broke.",
"Skips the stage-model selection step and goes straight to evidence collection for this refresh.",
"Diffs each signal against its previous value rather than restating only the current value.",
"Reports onboarding 34% to 39%, integration 52% to 49% and production 28% to 31% as movements against the previous map.",
"Names integration as the one stage whose rate moved backwards.",
"Compares only against this map's own previous version, not against any outside funnel.",
"Acknowledges the company-wide AARRR funnel as a genuine argument for AAARRRP, while subordinating it to continuity on a refresh.",
"States what would justify switching models later: the current model actually breaking.",
"Sets a re-read date, defaulting to 90 days and also triggered by a launch, a pricing change, a docs rewrite or a new SDK."
]
},
{
"id": 10,
"prompt": "Signals for the Marrowfen journey map - embeddable charting SDK, segment is frontend engineers at product companies, end state production usage. Here is what I have, and I want a complete map with a number in every row, no blanks anywhere:\n\n- Discover: total GitHub stars, 11,400\n- Evaluate: nothing instrumented\n- Try: cumulative signups, 22,900\n- Adopt: nothing instrumented\n- Contribute: nothing instrumented\n- Advocate: 4 conference talks by non-employees last quarter, which I'd like expressed as 4 of 112 production accounts = 3.6%\n\nOur company OKR this half is signups, so I want that one front and centre.",
"expected_output": "Monotonic counters rejected and converted, uninstrumented stages marked and listed in Gaps rather than filled, the signal-coverage gate reported as failed but the map shipped anyway, and the 4-event advocacy rate replaced by a dated raw list.",
"files": [],
"expectations": [
"Rejects total GitHub stars as a signal because it is a monotonic counter that cannot fall when the stage breaks.",
"Rejects cumulative signups on the same grounds.",
"Converts each monotonic counter into a rate or a period delta.",
"Refuses to invent numbers for the uninstrumented stages.",
"Writes 'not instrumented' in those rows instead.",
"Lists the uninstrumented stages in the map's Gaps section.",
"States the gate that at least 60% of stages must carry a real current value, and reports that this map carries 2 of 6 and fails that line.",
"Ships the map anyway rather than blocking on the coverage gap.",
"States that an honest map with named holes beats a complete map with invented numbers.",
"Labels the 60% coverage figure as this skill's own working default rather than an industry standard.",
"Replaces the 3.6% advocacy rate with a dated raw list, because 4 events sit below the roughly-30-event floor.",
"Pairs the signups OKR with a quality counter-metric, such as 30-day retention of the same signup cohort.",
"Applies the 'so what' test and the ownership test to each proposed signal."
]
},
{
"id": 11,
"prompt": "Don't need a discovery phase on this one - the whole team already agrees the problem is our SDK reference docs, we've been saying it for about a year. Company is Halloway, a payments API. Segment is engineers at e-commerce platforms, end state production usage. Support barely ever gets tickets about onboarding, so that part is clearly fine. Just write the map with SDK docs as the leak and we'll take it from there.",
"expected_output": "A refusal to build the map from the team's belief, the SDK-docs theory recorded as a hypothesis, an evidence plan ordered cheapest-first with the friction log and exit interview protocols specified, and a correction of the inference that few onboarding tickets means onboarding works.",
"files": [],
"expectations": [
"Declines to write the map from the team's existing belief.",
"States that a map assembled from opinion documents the team's beliefs, not the developer's path.",
"Records 'SDK reference docs' as the team's hypothesis rather than as friction evidence.",
"Orders evidence collection cheapest source first: walk the path and keep a friction log, mine what developers already wrote, interview developers, then read the funnel data that already exists.",
"Rejects the inference that few onboarding tickets means onboarding works.",
"States that developers who fail at setup rarely file anything, they leave.",
"Names the inverse signal: a stage with almost no questions and low conversion is a stage where people leave without speaking.",
"Specifies the friction log as one realistic scenario recorded as a running narrative, explicitly not minimal reproduction steps.",
"Requires the friction log to record verbatim search terms, clicked URLs and pasted commands, plus emotional reactions.",
"Names the green / yellow / red convention for delight, friction and blocking.",
"States that whoever is newest to the product makes the best friction logger.",
"Recommends interviewing 5 to 8 developers who completed the journey and 3 who abandoned it, and labels both counts as this skill's own defaults.",
"Instructs tagging each piece of evidence with the stage it belongs to before analysing it."
]
},
{
"id": 12,
"prompt": "Three things on my list for Sableworks, message-queue-as-a-service. Map the developer journey for our 'backend engineer at a scale-up' segment, end state production usage. Then rewrite our quickstart page so it converts better. And while you're in there, build me the DevRel KPI framework I have to present in November. Heads up on ownership: we're a three-person DevRel team and honestly we're the only ones who'd take any of these stages - docs, the dashboard, the SDK, community, all of it effectively lands on us because product is heads-down on the enterprise roadmap.",
"expected_output": "The journey map produced, the quickstart rewrite and the KPI framework declined and routed to the named sibling skills, and DevRel owning every row reported as an organisational finding that fails the gate without a fabricated owner being invented to pass it.",
"files": [],
"expectations": [
"Produces the developer journey map.",
"Declines to rewrite the quickstart page as part of this run.",
"Routes the quickstart rewrite to samber/developer-relations-skills@developer-quickstart-guide by name.",
"Gives the reason for routing it out: a one-stage fix does not need a seven-stage artefact.",
"Declines to build the DevRel KPI framework as part of this run.",
"Routes the KPI framework to samber/developer-relations-skills@devrel-metrics by name.",
"Reports DevRel owning every row as a finding about the organisation, not merely a detail of the map.",
"States that it means the surfaces have no accountable owner, which is a bigger problem than the leak itself.",
"Names the gate line that at least one owner must sit outside the DevRel team, and reports this map failing it.",
"Does not fabricate an external owner in order to satisfy that gate.",
"Produces the deliverable under its seven headings: Scope, Journey, Buyer lane, Moments, Leak, Handoff, Gaps.",
"Names the three moments separately: first success, moment of truth, abandonment point.",
"Presents the document section by section for agreement rather than delivering it all at once."
]
}
],
"trigger_queries": [
{ "query": "Map the developer journey for our API product", "should_trigger": true },
{ "query": "I need a developer journey map for our SDK", "should_trigger": true },
{ "query": "Can you build us a developer adoption funnel?", "should_trigger": true },
{ "query": "What does our developer journey actually look like right now?", "should_trigger": true },
{ "query": "Journey map for our platform engineer segment please", "should_trigger": true },
{ "query": "Refresh last quarter's developer journey map", "should_trigger": true },
{ "query": "Map the path from first visit to production usage for our developers", "should_trigger": true },
{ "query": "We need a stage-by-stage view of how developers adopt our tool", "should_trigger": true },
{ "query": "Build a map from onboarding all the way through to advocacy", "should_trigger": true },
{ "query": "Where does our developer funnel drop off?", "should_trigger": true },
{ "query": "Developers try it and never reach production - where are we losing them?", "should_trigger": true },
{ "query": "Who owns each step of our developer experience?", "should_trigger": true },
{ "query": "Nobody owns the docs-to-signup handoff and I want to prove it", "should_trigger": true },
{ "query": "We lose people somewhere between the quickstart and production", "should_trigger": true },
{ "query": "How do developers become contributors on our project?", "should_trigger": true },
{ "query": "Map the contributor journey for our open source repo", "should_trigger": true },
{ "query": "Which of our five adoption stages should we fix first?", "should_trigger": true },
{ "query": "I already have a stage list, just tell me which one is leaking", "should_trigger": true },
{ "query": "we lose people somewhere", "should_trigger": true },
{ "query": "tons of signups, almost nobody sticks around, no idea where they go", "should_trigger": true },
{ "query": "people star the repo and then vanish", "should_trigger": true },
{ "query": "our funnel is a black box after the docs page", "should_trigger": true },
{ "query": "I can't explain to my VP where engineers drop off", "should_trigger": true },
{ "query": "what happens between someone hearing about us and actually shipping with us?", "should_trigger": true },
{ "query": "everyone tries it, nobody deploys it", "should_trigger": true },
{ "query": "we get first API calls and then silence", "should_trigger": true },
{ "query": "I want a picture of the whole path a developer walks with us", "should_trigger": true },
{ "query": "can you chart out how someone goes from never heard of us to telling their friends?", "should_trigger": true },
{ "query": "we have no idea which team is accountable for the setup experience", "should_trigger": true },
{ "query": "trying to figure out the biggest hole in how devs adopt our product", "should_trigger": true },
{ "query": "our enterprise deals stall but the devs love us - what does the whole path look like?", "should_trigger": true },
{ "query": "how do I show the board where developer adoption breaks?", "should_trigger": true },
{ "query": "is the leak in evaluation or in onboarding? I want evidence, not opinions", "should_trigger": true },
{ "query": "put together a stage model with owners and exit events for our devtool", "should_trigger": true },
{ "query": "what's the moment of truth for developers using our CLI?", "should_trigger": true },
{ "query": "where is our abandonment point?", "should_trigger": true },
{ "query": "I want to know our time to first success and what happens after it", "should_trigger": true },
{ "query": "we need one artifact that shows the developer path plus who owns each bit", "should_trigger": true },
{ "query": "map how platform teams go from evaluating us to standardising on us", "should_trigger": true },
{ "query": "why do teams adopt us but the org never standardises?", "should_trigger": true },
{ "query": "our developers love it but procurement kills it - I need both paths on one page", "should_trigger": true },
{ "query": "I want a buyer lane next to our developer funnel", "should_trigger": true },
{ "query": "who signs, and where do they show up in the developer path?", "should_trigger": true },
{ "query": "can you diagram our developer lifecycle with a metric per stage?", "should_trigger": true },
{ "query": "we need exit events for each stage of developer adoption", "should_trigger": true },
{ "query": "build the adoption map for our Rust SDK, backend engineers at startups", "should_trigger": true },
{ "query": "quarterly planning needs a view of where devs fall out", "should_trigger": true },
{ "query": "which stage of our developer funnel deserves next quarter's engineering time?", "should_trigger": true },
{ "query": "map it and tell me the one thing to fix", "should_trigger": true },
{ "query": "I need to know where first-time contributors give up", "should_trigger": true },
{ "query": "first PRs come in and then those people never return - map it out", "should_trigger": true },
{ "query": "what does the path look like from npm install to production?", "should_trigger": true },
{ "query": "we're guessing about where developers churn and I'd like to stop guessing", "should_trigger": true },
{ "query": "can you lay out discovery through advocacy for our open source project?", "should_trigger": true },
{ "query": "draw the developer adoption lifecycle for our observability agent", "should_trigger": true },
{ "query": "our activation number is bad but I don't know which step causes it", "should_trigger": true },
{ "query": "help me figure out which part of the developer experience nobody is accountable for", "should_trigger": true },
{ "query": "I want a one-page view of developer adoption with a signal per stage", "should_trigger": true },
{ "query": "what stages should our developer funnel even have?", "should_trigger": true },
{ "query": "should we use AARRR or something developer-specific for our adoption stages?", "should_trigger": true },
{ "query": "pick a stage model for our developer funnel and justify the choice", "should_trigger": true },
{ "query": "we blended two adoption frameworks and now nothing lines up", "should_trigger": true },
{ "query": "map the developer path for hobbyists separately from enterprise", "should_trigger": true },
{ "query": "we're losing people and the team all has different theories about where", "should_trigger": true },
{ "query": "our support tickets cluster somewhere but I don't know which stage that is", "should_trigger": true },
{ "query": "show me the developer path plus what evidence backs each stage", "should_trigger": true },
{ "query": "I need to request instrumentation but first I need to know what's dark", "should_trigger": true },
{ "query": "which parts of our developer funnel are we blind to?", "should_trigger": true },
{ "query": "how do we go from 'they tried it' to 'they depend on it'?", "should_trigger": true },
{ "query": "our devs go quiet after onboarding and I want the map that explains it", "should_trigger": true },
{ "query": "Which developer audience should we target first?", "should_trigger": false },
{ "query": "How big is the Go ecosystem for a tool like ours?", "should_trigger": false },
{ "query": "Write an anti-segment for our developer audience", "should_trigger": false },
{ "query": "Who is this devtool actually for?", "should_trigger": false },
{ "query": "What DevRel KPIs should I report to the exec team?", "should_trigger": false },
{ "query": "Build our developer relations measurement framework", "should_trigger": false },
{ "query": "How do I prove DevRel ROI to a CFO?", "should_trigger": false },
{ "query": "Which vanity metrics should we cut from our devrel report?", "should_trigger": false },
{ "query": "Our GitHub numbers don't match our analytics, help", "should_trigger": false },
{ "query": "Set up UTM discipline for our docs links", "should_trigger": false },
{ "query": "Design an event taxonomy for our documentation site", "should_trigger": false },
{ "query": "How do we join docs traffic to signups in our warehouse?", "should_trigger": false },
{ "query": "Rewrite our getting started page so people finish it", "should_trigger": false },
{ "query": "Our hello world takes 40 minutes - fix the quickstart", "should_trigger": false },
{ "query": "Write a quickstart for our REST API", "should_trigger": false },
{ "query": "Our docs are a mess, reorganise them", "should_trigger": false },
{ "query": "Audit our documentation against Diataxis", "should_trigger": false },
{ "query": "Where should this page live in our docs tree?", "should_trigger": false },
{ "query": "Write a CONTRIBUTING.md for our repo", "should_trigger": false },
{ "query": "Our good first issues get no takers", "should_trigger": false },
{ "query": "Design our open source issue triage system", "should_trigger": false },
{ "query": "Is our Discord dying?", "should_trigger": false },
{ "query": "Build a community health dashboard", "should_trigger": false },
{ "query": "Should we launch a Discord or a forum?", "should_trigger": false },
{ "query": "Write our community code of conduct enforcement process", "should_trigger": false },
{ "query": "Should we go bottom-up or hire an enterprise sales team?", "should_trigger": false },
{ "query": "When should sales contact a free-tier user?", "should_trigger": false },
{ "query": "How do we price our developer tool's free tier?", "should_trigger": false },
{ "query": "Usage-based or seat-based pricing for our API?", "should_trigger": false },
{ "query": "Open core or managed cloud - which business model?", "should_trigger": false },
{ "query": "Design an ambassador program for our community", "should_trigger": false },
{ "query": "How do we recognise our top community members?", "should_trigger": false },
{ "query": "Should we start doing DevRel at all?", "should_trigger": false },
{ "query": "Which DevRel pillar deserves our next hire?", "should_trigger": false },
{ "query": "What should a new devrel person do in their first 90 days?", "should_trigger": false },
{ "query": "How should I split our DevRel budget across events and content?", "should_trigger": false },
{ "query": "Plan our devrel content calendar for Q3", "should_trigger": false },
{ "query": "Write the job description for a senior developer advocate", "should_trigger": false },
{ "query": "How do I get promoted from advocate to head of DevRel?", "should_trigger": false },
{ "query": "How should our DevRel team be structured?", "should_trigger": false },
{ "query": "Turn these commits into release notes", "should_trigger": false },
{ "query": "Write a migration guide for our v3 breaking changes", "should_trigger": false },
{ "query": "Rewrite our README so it converts", "should_trigger": false },
{ "query": "Get our docs ranking for 'rate limiting python'", "should_trigger": false },
{ "query": "Find the keywords developers actually search in our category", "should_trigger": false },
{ "query": "Write a tutorial teaching webhooks with our SDK", "should_trigger": false },
{ "query": "Set standards for code samples across our docs", "should_trigger": false },
{ "query": "Make our docs easier for coding agents to consume", "should_trigger": false },
{ "query": "Write a troubleshooting page for our most common errors", "should_trigger": false },
{ "query": "Draft a CFP abstract for KubeCon", "should_trigger": false },
{ "query": "Outline a 25-minute conference talk about our architecture", "should_trigger": false },
{ "query": "Design a live demo that won't break on stage", "should_trigger": false },
{ "query": "Script a 6-minute product video for developers", "should_trigger": false },
{ "query": "Prep me for a podcast interview about our open source project", "should_trigger": false },
{ "query": "Write a case study about how Acme uses our API", "should_trigger": false },
{ "query": "Draft an engineering blog post about our storage rewrite", "should_trigger": false },
{ "query": "Pitch our launch to tech press", "should_trigger": false },
{ "query": "Plan our Show HN launch", "should_trigger": false },
{ "query": "Should we sponsor this conference or run our own meetup?", "should_trigger": false },
{ "query": "Start a monthly developer meetup in Berlin", "should_trigger": false },
{ "query": "Pick a license for our new open source project", "should_trigger": false },
{ "query": "Set up governance for our CNCF-bound project", "should_trigger": false },
{ "query": "How do we get companies to sponsor our OSS work?", "should_trigger": false },
{ "query": "Should we push our wire format through a standards body?", "should_trigger": false },
{ "query": "Which registries should we publish our SDK to?", "should_trigger": false },
{ "query": "Build a customer journey map for our ecommerce checkout", "should_trigger": false },
{ "query": "Create a user journey map for our mobile app onboarding", "should_trigger": false },
{ "query": "Map the B2B buyer journey for our sales team", "should_trigger": false },
{ "query": "Build a service blueprint for our support organisation", "should_trigger": false },
{ "query": "Make an empathy map for our primary persona", "should_trigger": false }
]
}
references/evidence-and-signals.md›
# Evidence, signals and owners per stage
What to look for, what to count, and who usually owns it. Adapt the owner column to the actual org - the point of the column is that it names someone, not that it matches this table.
## Contents
- [Per-stage table](#per-stage-table)
- [Buyer-lane signal families](#buyer-lane-signal-families)
- [The friction log protocol](#the-friction-log-protocol)
- [The exit interview protocol](#the-exit-interview-protocol)
- [Support-signal mining](#support-signal-mining)
- [What each surface can physically report](#what-each-surface-can-physically-report)
- [Signal hygiene](#signal-hygiene)
## Per-stage table
Stage names below use the unsourced discover → advocate spine; map them onto whichever model the skill selected.
| Stage | Evidence to gather | Candidate signals (pick one) | Usual owner |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------- |
| Discover | where inbound actually comes from; search queries that reach the docs; which communities mention the product; self-reported "how did you hear about us" free text | new self-reported first touches per month, by source | marketing or DevRel |
| Evaluate | friction log of a first read; docs searches returning nothing; comparison questions in community threads; competitor pages developers land on next | docs sessions reaching a decision page; repo clones; trial starts | docs owner or product marketing |
| Try | cold-run of the quickstart on a clean machine; step-level drop-off; time from signup to first result; the errors that appear in the first hour | median time to first success, and share of starters reaching it | developer experience or docs |
| Adopt | interviews about what got the product into a real project; the approval steps inside the user's own company; incident and limits questions | share of first-success users still active at 30 days; workloads in production | product |
| Contribute | first-PR experience walkthrough; setup failures on machines the maintainers never tested; time to first review response | first-time contributors per quarter; share who return for a second contribution | maintainers |
| Advocate | who already talks about the product unprompted; which of them got any support for it | unprompted public mentions by named practitioners; talks or posts by non-employees | community or DevRel |
Two stages have published evidence about what developers actually do there; use it to aim the questions rather than to fill the cells.
- **Evaluate.** Larios Vargas et al. (ESEC/FSE 2020, DOI 10.1145/3368089.3409711; 16 interviews, 115 survey respondents) ranked what developers say drives library selection: maturity/stability 62%, usability 55%, documentation 51%, license 45%, active maintenance 44%, security 39%, popularity 30% rated "highly influential". Same study, one interviewee: _"Checking security vulnerabilities is important, but I do not check it up-front."_ Read the ranking as a checklist of what an evaluation-stage surface has to answer, and read the quote as the reason to cross-check any self-report against behaviour.
- **Contribute.** GitHub's Open Source Guides report that contributors who received code review within 48 hours had a much higher rate of return and repeat contribution, and that "it only takes one negative experience to make someone not want to come back". Time-to-first-review is therefore the contribution stage's default signal, and the stage's exit event is the merge, not the submission.
Buyer lane, when the developer is not the buyer:
| Buyer stage | Evidence | Candidate signal | Usual owner |
| ------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------- | --------------------------------- |
| Technical approval | security questionnaires received; the questions that stall; architecture review objections | evaluations that clear security review | security or solutions engineering |
| Commercial approval | licensing and dependency-policy blockers; procurement timelines | days from first approver contact to signature | sales or finance |
## Buyer-lane signal families
The developer lane counts people; the buyer lane counts accounts. Roll individual usage up to an account before reading anything in this lane - email domain, workspace or organisation object, licence or API key, or self-reported company. Each is imperfect; a lane with no rollup cannot be read at all, because forty signups from one company look like forty leads.
Three families, in increasing order of buying intent:
| Family | What it looks like | Where it sits on the map |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Depth | production environment, sustained volume, wired into CI or a deployment pipeline, retention over weeks rather than a spike | the developer lane's adoption/production stage, read at account level |
| Spread | a second and third active developer in the same account, a shared workspace, invites sent, several repos or services | the entry trigger for the buyer lane - one developer is evaluation, three is a decision |
| Boundary contact | someone opened an SSO or RBAC page, asked an audit or compliance question, hit a rate or seat limit, requested a security questionnaire, or looked at enterprise terms | the strongest and rarest signal, and the cleanest exit event for the buyer lane's first stage |
Boundary contact is the one worth instrumenting first: it is the only signal that maps directly onto the paid boundary, and it is cheap to capture because it is a page view or a support request the product already sees.
Record the champion explicitly as a row participant, not as a persona note. The champion argues the case when nobody from the vendor is in the room, so the artefact they carry - an internal one-pager, a re-runnable benchmark, a reference architecture, pre-answered licence and data-handling questions - is the buyer lane's real touchpoint. A pack nobody opens is evidence the champion does not exist yet, which is itself a finding about the stage.
## The friction log protocol
Google's DevRel practice popularised this artefact (Aja Hammerly, "An introduction to friction logging", developerrelations.com, 8 July 2018), and it remains the cheapest high-quality evidence for a journey map.
- Header: your name, platform, language, browser, date, product version.
- Scenario: one realistic use case in under two sentences, familiar enough that nobody asks "why would someone do that?".
- Body: a running log of actions and reactions. Record the search terms you used, which result you clicked and its URL, the commands and code you pasted verbatim, and your emotional reactions ("now I'm frustrated", "copied this from the docs without reading the prose").
- Convention: green for delight, yellow for friction, red for blocking.
- Unlike a bug report, minimal reproduction steps are not the goal - the narrative is.
Whoever is newest to the product is the best logger, because veterans route around rough spots without noticing.
## The exit interview protocol
Recruiting people who abandoned the journey is hard and worth the effort; they are the only witnesses to the stages that leak silently.
1. Open by removing the sales frame: you are not trying to win them back, only to understand the experience.
2. "Walk me through your experience with the product, from first contact to today."
3. "Was there a specific moment when you decided to stop?"
4. "What are you using instead, and what made it a better fit?"
5. "If you could change one thing, what would it be?"
Tag each answer with the stage it belongs to before analysing. Three abandonment interviews usually relocate the team's assumed leak by at least one stage.
## Support-signal mining
- Pull the last quarter of tickets, issues and community questions.
- Tag each by the stage the asker was in, not by product area.
- Count clusters, then check the biggest cluster against the friction log - a cluster can mean high friction or simply high traffic at that stage.
- Watch for the inverse signal: a stage with almost no questions and low conversion is a stage where people leave without speaking.
## What each surface can physically report
Before promising a signal, check the surface can produce it and check what it silently distorts. Three corrections change a developer journey map's numbers more than anything else.
**Analytics blocking.** Plausible Analytics measured its own proxied script against a third-party analytics script on a site carrying Hacker News and Reddit traffic (August 2021) and found **58% of that tech audience blocked the third-party script**. The breakdown: 82.3% on Linux, 88.3% on Firefox, 68.2% on desktop versus 49.9% on mobile.
A docs-site session count is therefore roughly measuring the non-developer half of a developer audience, and the blocking rate varies by page: an install page loses far more than a pricing page. Consequences for the map:
- never write an absolute traffic number in a cell
- compare step-to-step ratios inside one source
- fix it in cost order: first-party or proxied script, then server/CDN log analysis, then a product-side event for anything past signup
**Retention windows.** Three sources expire on their own schedule and cannot be backfilled:
- repository traffic endpoints keep **14 days** and need write access to that repository
- npm download data 18 months
- PyPI time series 180 days
- chat venues cap history by plan
Any signal drawn from those has to be snapshotted into your own store from the day it is defined, or next quarter's re-read has no baseline to compare against.
**Referrer loss.** Aggregators, chat clients, privacy browsers and slide links strip referrers, and roughly 70% of AI-assistant-driven traffic arrives with no referrer at all. A large "direct" bucket on the discovery stage is the normal case, not an instrumentation bug - label the stage inferred and move on rather than chasing it.
Two registry footnotes worth knowing before a download count becomes a signal: npm counts HTTP 200 responses for tarballs, including build servers and mirrors, so it is a request count and not a person count; PyPI excludes known mirrors by default. The two are not comparable, and neither is a user count.
## Signal hygiene
- **One signal per stage.** More turns the map into a dashboard and hides the decision.
- **Reject monotonic counters.** Total stars, cumulative signups and all-time downloads only go up and cannot fall when the journey breaks. Convert to a rate or a period delta.
- **Apply the "so what" test.** If the number moved 20% next month, would anyone act? If not, it is decoration.
- **Apply the ownership test.** Can the named owner plausibly move it within the review period?
- **Pair an incentivised volume metric with a quality counter-metric.** Rewarding signups produces throwaway accounts; pair it with 30-day retention of the same cohort. Rewarding closed issues produces premature closes; pair it with reopen rate.
- **Respect the small-N floor.** Below roughly 30 events in a period, publish the raw list with dates rather than a percentage.
- **State the attribution bias.** Self-reported attribution over-counts memorable touches and under-counts docs and search; tagged links under-count everything not clicked from a taggable surface and inflate "direct". Pick one, state its bias, hold it constant across quarters.
references/journey-map-example.md›
# Worked example and row quality
A fictional but realistic map, followed by weak-versus-strong versions of each column.
- **Product:** a hosted queue service with an SDK, sold self-serve with an enterprise tier.
- **Segment:** a backend engineer at a 50-500 person company.
- **End state:** production usage.
## Contents
- [The map](#the-map)
- [Buyer lane](#buyer-lane)
- [Moments](#moments)
- [Leak diagnosis](#leak-diagnosis)
- [Weak vs strong rows](#weak-vs-strong-rows)
## The map
Stage model: API and platform five-stage arc, chosen because the end state is production usage and the team already counts first API calls.
| Stage | Developer's job | Entry trigger | Exit event | Touchpoints | Owner | Friction evidence | Signal |
| ----------- | ----------------------------------------------------- | ------------------------ | -------------------------------------------------------------- | --------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Awareness | "find something better than the queue we hand-rolled" | search or peer mention | lands on docs or repo | search results, community threads, comparison posts | growth marketing | 41 of 78 signup surveys last quarter said "colleague" - inferred, self-reported | 78 self-reported first touches/quarter (inferred) |
| Onboarding | "prove it works from my laptop" | opens the quickstart | first successful publish + consume from local code | quickstart, SDK install, dashboard, API keys | developer experience | friction log 2026-08-14: key creation buried two clicks past a plan chooser; 11 min of 19 min run spent on auth | median 19 min to first success; 34% of quickstart starters reach it |
| Integration | "wire it into our service behind a feature flag" | first success reached | SDK called from a service repo on a shared branch | SDK reference, error docs, support | product | 23 of 61 tickets last quarter were retry/idempotency semantics, all from this stage | 46% of first-success users make a call from a non-local IP within 30 days |
| Production | "own this on call" | staging traffic observed | sustained traffic for 14 days plus an alerting rule configured | runbooks, status page, limits docs, support | product | 3 of 3 exit interviews cited no documented failure semantics as the blocker | 22% of integrating accounts reach 14-day sustained traffic |
| Advocacy | "tell people it saved us" | six months in production | public talk, post or unprompted recommendation | community, conference CFPs, changelog | DevRel | none gathered yet | 4 unprompted public mentions last quarter (raw list, below small-N floor) |
## Buyer lane
Present: the enterprise tier requires a security review. Two stages, both owned outside DevRel.
| Buyer stage | Exit event | Owner | Signal |
| ------------------- | ------------------------------------------- | --------------------- | --------------------------------------------------------------- |
| Technical approval | security questionnaire returned and cleared | solutions engineering | 6 of 9 questionnaires cleared last quarter |
| Commercial approval | contract signed | sales | median 38 days from first approver contact (n=9, raw list kept) |
## Moments
- **First success**: first message published and consumed from local code. Median 19 minutes today.
- **Moment of truth**: the decision to put it behind a feature flag in a real service - this is where the team stops evaluating and starts depending.
- **Abandonment point**: inside onboarding, at API-key creation, earlier than the team assumed. The assumption before the map was that people churned during integration.
## Leak diagnosis
Onboarding. 34% of quickstart starters reach first success, the lowest owned conversion on the map, and it is the earliest stage with both a measured rate and an owner able to change it (developer experience owns the quickstart and the key-creation flow). Integration converts worse in absolute terms at 46%, but it sits downstream, so fixing onboarding raises its input volume before its rate is worth touching.
Handoff:
- developer experience owns the fix
- the signal to watch is share of quickstart starters reaching first success
- re-read the map in 90 days
Gaps: the awareness row is inferred from a self-report survey with a 12% response rate. Advocacy is below the small-N floor and stays a raw list until it is not.
## Weak vs strong rows
**Exit event**
- Weak: "developer understands the value proposition." Cannot be observed, counted or owned, so no one can be accountable for it.
- Strong: "first message published and consumed from local code." One event, already logged, unambiguous.
**Owner**
- Weak: "DevRel" in every row. Means nobody negotiated the map with the teams that own the surfaces.
- Strong: "developer experience" for onboarding, "product" for integration and production, "sales" for commercial approval - and the map notes that no one owns awareness, which is itself the finding.
**Friction evidence**
- Weak: "developers find auth confusing." A hypothesis wearing an evidence costume.
- Strong: "friction log 2026-08-14: key creation buried two clicks past a plan chooser; 11 of 19 minutes spent on auth." Cited, dated, reproducible.
**Signal**
- Weak: "total signups: 4,300." Monotonic, cannot fall when the stage breaks, and covers three stages at once.
- Strong: "34% of quickstart starters reach first success." A rate, scoped to one stage, movable by the named owner.
**Developer's job**
- Weak: "user enters the consideration phase." Describes the vendor's funnel, not a person's task.
- Strong: "prove it works from my laptop before I bring it to the team." A sentence a developer would recognise as their own.
**Leak diagnosis**
- Weak: "our 34% quickstart conversion is below the 40-60% industry benchmark, so onboarding is broken." The benchmark does not exist. Every number in circulation for this stage is one company's anecdote, measured against a different audience, a different product maturity and a different definition of "started". A map that argues from a borrowed rate cannot be checked, and it hides the only comparison that means anything.
- Strong: "34% of quickstart starters reach first success, down from 41% in the May map, and it is the earliest measured stage with an owner who can change it." Compared against itself, over a stated period, with the owner named in the same sentence.
**Why the stage leaks (B=MAP)**
- Weak: "developers aren't motivated to finish onboarding - we should add a value-prop banner above the quickstart." Reaches for motivation because copy is cheaper to write than steps are to remove. The friction log already said 11 of 19 minutes went to authentication, which is an ability problem, and no banner shortens it.
- Strong: "ability. The Ability Chain's weakest link here is time: key creation costs 11 of the run's 19 minutes because it sits two clicks past a plan chooser. Removing the plan chooser from the first-key path is the test." Names the branch, names the scarce resource, and proposes something falsifiable.
**Buyer lane**
- Weak: a lane with one row reading "enterprise deals - sales owns it", drawn from a list of individual signups. Forty developers from one company read as forty leads, so nothing in the lane can be counted.
- Strong: usage rolled up to an account by email domain, with three signals named:
- depth (14-day sustained traffic)
- spread (three active developers in one workspace)
- boundary contact (someone opened the SSO page)
Boundary contact is used as the lane's entry trigger, because it is the only one that maps onto the paid boundary.
- Also weak, in the other direction: an empty buyer lane on a self-serve product. Write "none - the developer decides and pays" explicitly, so the next reader knows it was decided rather than forgotten.
references/published-findings.md›
# Published findings
Where every number and named model in this skill comes from, and which ones are this skill's own defaults. Read this before quoting a figure to a user or defending a threshold.
The short version: the journey _vocabulary_ is published and citable. Per-stage _conversion rates_ are not: the figures in circulation are single-company anecdotes with incompatible stage definitions, so no "normal" discovery-to-production rate can be quoted. Every rate in a map has to come from the product's own data, and every comparison has to be against the same map's previous version.
## Contents
- [Sourced claims and their sources](#sourced-claims-and-their-sources)
- [Self-set baselines](#self-set-baselines)
- [Claims to refuse](#claims-to-refuse)
- [Practitioner voices](#practitioner-voices)
- [Named frameworks and their limits](#named-frameworks-and-their-limits)
## Sourced claims and their sources
| Claim | Source |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Six-stage developer journey: initial awareness → deep awareness → evaluation and validation → commitment → standardization → community and advocacy | Matthew Revell, developerrelations.com, 16 June 2016, published alongside the CORE framework |
| The same guide defers per-stage measurement to "a future guide" that was never published | Revell, same source - the field's clearest admission that per-stage measurement is unsolved |
| AAARRRP (awareness, acquisition, activation, retention, referral, revenue, product) | Phil Leggetter, 2016, `leggetter.co.uk/aaarrrp/`, adapted from Dave McClure's AARRR |
| Orbit levels (explorer → participant → contributor → advocate) and gravity = love × reach | Orbit Model, developed from 2014, published on GitHub November 2019; no longer under active development |
| Contributors who received code review within 48 hours had a much higher rate of return and repeat contribution; "it only takes one negative experience to make someone not want to come back" | GitHub Open Source Guides, `opensource.guide/building-community/` |
| Newcomers pick tasks by required API domain, not by a maintainer's difficulty label - API-domain labels were selected more often than architecture-based ones in a 74-participant study | Santos et al. / Steinmacher, arXiv:2103.12653 |
| The friction log: single-scenario narrative, verbatim search terms and commands, green/yellow/red convention, newest person is the best logger | Aja Hammerly (Google), "An introduction to friction logging", developerrelations.com, 8 July 2018 |
| Developers rank library-selection factors: maturity/stability 62%, usability 55%, documentation 51%, license 45%, active maintenance 44%, security 39%, popularity 30% "highly influential" | Larios Vargas et al., ESEC/FSE 2020, DOI 10.1145/3368089.3409711 - 16 interviews plus 115 survey respondents |
| Stated criteria and actual behaviour diverge: "Checking security vulnerabilities is important, but I do not check it up-front" | Larios Vargas et al., interviewee quote - direct evidence that an evaluation-stage self-report needs a behavioural cross-check |
| Three of four developers consider stars before adopting or contributing, and 36.7% starred a repository _because_ they were already using it | Borges & Valente, _Journal of Systems and Software_, 2018 (arXiv:1811.07643), 791 developers |
| 58% of a tech audience blocks third-party analytics scripts - Linux 82.3%, Firefox 88.3%, desktop 68.2% versus mobile 49.9% | Plausible Analytics, "Google Analytics is blocked by adblockers", August 2021, measured against its own proxied script on a site carrying Hacker News and Reddit traffic |
| Roughly 70% of AI-assistant-driven traffic arrives with no referrer and lands in "direct" | Demand Curve newsletter #331 |
| Repository traffic endpoints (views, clones, referrers) retain **14 days** and require write access to that repository; npm download data 18 months, PyPI time series 180 days | GitHub REST "Metrics / Traffic" documentation and pypistats.org API docs |
| Observational attribution overstates true lift by roughly 7-9x for paid media; a properly powered advertising experiment "can easily require more than ten million person-weeks" | Gordon et al., _Marketing Science_, 2019; Lewis & Rao, 2015 |
| "When a measure becomes a target, it ceases to be a good measure" | Marilyn Strathern, 1997, generalising Charles Goodhart, 1975 |
| GitHub stars are "the Monopoly money of open-source metrics"; API call data is "the Holy Grail of metrics" | Ashley Hathaway, "Developer evangelism and GitHub metrics", developerrelations.com, 2 August 2017 |
| B = MAP: a behaviour happens when motivation, ability and a prompt converge; ability is set by the scarcest link in what Fogg calls the Ability Chain - time, money, physical effort, mental effort and routine; "we've already established that motivation is unreliable. Luckily, ability is not." | BJ Fogg, _Tiny Habits: The Small Changes That Change Everything_ (2019); the underlying three-factor model was first published as the Fogg Behavior Model, Stanford Behavior Design Lab, behaviormodel.org - whose own earlier six-factor "Simplicity" formulation adds a sixth ability factor, social deviance, that the Ability Chain in _Tiny Habits_ drops |
| The DevRel Qualified Lead as a non-sales currency for a passed connection | Mary Thengvall, 14 December 2019 |
| Across 2,600+ companies' instrumented usage data (September 2023 - September 2024), a signup cohort's day-7 return rate of 7% places a B2B technology product in the top quartile for activation; median performers reach only 2.1% | Amplitude, "The 7% Retention Rule" and "B2B Technology Product Benchmarks", 2025 |
| A 1,000+-respondent developer-tools product survey declines to publish one activation-rate figure, because the milestone differs by product (a Loom share, a Zapier zap, a completed Zoom meeting); the same survey reports 10% median visitor-to-signup, 30%/23% retention at 7/28 days, and 5-10% free-to-paid conversion within 6 months for developer tools | OpenView 2023 Product Benchmarks, developer-tools subset, republished by Anna Debenham, boldstart ventures |
| The one activation-rate figure with a stated formula (activated users divided by completed signups, milestone required to show at least a 2x retention differential) comes from a 500+-product self-reported survey: median 25%, average 34% overall; median 30%, average 36% restricted to SaaS | Lenny Rachitsky and Yuriy Timen, "What's a good activation rate", lennysnewsletter.com, 2022 |
## Self-set baselines
None of these has a published study behind it. They are this skill's defaults, chosen because they make a map decidable. Present them as adjustable starting points, and say so when a user asks where the number comes from.
| Baseline | Value | Why this number |
| ------------------------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Stage count | 5-7 | Fewer hides the leak inside a stage; more produces stages nobody can name an exit event for |
| Signal coverage to pass | 60% of stages carrying a real current value | Enough to compute at least one honest conversion rate while leaving room for the genuinely dark early stages |
| Completed-journey interviews | 5-8 | Matches the panel size usability research settles on; enough to hear a pattern twice |
| Abandonment interviews | 3 | The realistic recruiting ceiling, and three is usually enough to relocate an assumed leak by one stage |
| Leaks nominated per cycle | Exactly 1 | Three priorities is none, and the earliest-owned rule already produces a unique answer |
| Owners outside DevRel | At least 1 | A map where DevRel owns every row was never negotiated with the teams that own the surfaces |
| Re-read horizon | 90 days, and always after a launch, pricing change, docs rewrite or new SDK | Two quarters is long enough for a surface to have moved under the map |
| Signals per stage | Exactly 1 | More turns the map into a dashboard and hides the decision |
| Stage-model effort and efficiency ordering | API arc, OSS funnel, AAARRRP, Revell, unsourced default | Reasoned from what evidence each model's boundaries need before they can be counted, and meant to be re-ranked against what a team already instruments |
| No value ordering across stage models | deliberate | A model's value is decided entirely by whether its terminal stage is the funded end state, so a fixed order would be false precision - the end state deletes models instead of ranking them |
The small-N floor - publish the raw list with dates below roughly 30 events in a period instead of a rate - is a statistical convention, not a DevRel finding. Treat it as a discipline, not a citation.
## Claims to refuse
- **Any per-stage conversion benchmark from another company.** The figures circulating, including the five-stage API model's own numbers, are single-company anecdotes with no stated methodology. A map that compares itself to one is comparing across different audiences, product maturity and stage definitions at once.
- **A single global self-serve activation percentage**, such as the unattributed "20-40%" figure. No instrumented, milestone-based, developer-tools-specific study publishes one - the developer-tools survey above explicitly declines to give one, because the milestone differs by product. The nearest real numbers are a self-reported survey's median-to-average band (25-36%, see the sourced claims above) and an instrumented day-7-retention proxy under a different definition of activation entirely (2.1% median, 7% top quartile); the popular round figure collapses two different metrics into one number. Cite the actual source and its caveats, never the bare rounded figure, and never as a target.
- **Emotion scores per stage.** Generic journey maps carry them; at developer volumes they are not measurable, and they displace the columns that carry accountability.
- **Absolute traffic numbers from a third-party analytics script on a developer surface.** The Plausible measurement above means a docs-site session count is roughly measuring the non-developer half of the audience, and the blocking rate varies by page. A Linux install page is blocked far harder than a pricing page. Ratios inside one source survive; absolutes do not.
- **An attribution number presented without its bias direction.** Self-reported attribution over-counts memorable touches. Tagged links inflate "direct". Influenced pipeline over-counts by construction.
- **A rate computed from fewer than about 30 events.** Publish the dated raw list instead.
## Practitioner voices
- Hathaway on what to count instead of stars: outside contributions, forks, clones, downloads, pull requests and conversations - and "developer communities are not one single number to rule them all".
- Thengvall on the revenue question: "I don't believe DevRel or Community teams should ever (_EVER!_) have sales metrics to gauge their success. It muddies our work too much and changes what should be a genuine relationship into one that revolves around money." The opposing position - influenced pipeline, explicitly shared and never presented without the word "influenced" - is equally defensible; which one applies depends on who funds the team.
- Hammerly on who should write the friction log: new hires, because they lack the inside knowledge that lets veterans route around rough spots without noticing.
- Fogg on where to spend the effort: "simplicity changes behavior" - raise ability rather than pump motivation, because motivation arrives in waves and crashes.
## Named frameworks and their limits
Two frameworks are named in this skill, and each answers a different question:
- **A stage model** (Revell, AAARRRP, Orbit, the API five-stage arc, the OSS contributor funnel) answers _where in the journey a developer is_. It says nothing about owners, exit events or why a stage fails.
- **B=MAP** answers _why one already-chosen stage leaks_ - motivation, ability or prompt. It cannot rank stages against each other, so it runs after the leak is picked, never instead of picking it.
The table shape itself comes from generic customer-journey mapping; everything developer-specific sits in those two frameworks, and the quality gate in the skill body is self-set.
references/stage-models.md›
# Developer journey stage models
Five stage vocabularies are in circulation. Pick one, keep its published names, and do not blend two - blended models produce stages with no agreed definition and two competing terminal states.
## Contents
- [The five models](#the-five-models)
- [Choosing between them](#choosing-between-them)
- [The unsourced default](#the-unsourced-default)
- [Why the tails disagree](#why-the-tails-disagree)
- [What the map has to add](#what-the-map-has-to-add)
## The five models
### 1. Revell's six-stage developer journey
Initial awareness → deep awareness → evaluation and validation → commitment → standardization → community and advocacy.
Matthew Revell, developerrelations.com, 16 June 2016, published alongside the CORE situational-analysis framework. The only published model with an explicit enterprise standardisation stage, where a tool stops being one team's choice and becomes an organisation's default.
Strong when: the product is a commercial developer platform sold into companies, and the interesting question is why teams adopt it but the organisation never standardises on it.
### 2. AAARRRP
Awareness → acquisition → activation → retention → referral → revenue → product.
Phil Leggetter, 2016, `leggetter.co.uk/aaarrrp/`, adapted from Dave McClure's AARRR "pirate metrics" with a seventh element for developer products: users and the DevRel team help define and build the product.
Strong when: the map has to line up with a company-wide funnel other teams already use, or the conversation ends in a revenue question. Weak when the desired end state is contribution rather than purchase - it has no vocabulary for that.
### 3. Orbit levels
Explorer → participant → contributor → advocate.
Orbit Model, developed by developer advocates from 2014, published on GitHub November 2019; no longer under active development, so cite it as a stable framework rather than a maintained product. Its two axes - love (depth of engagement with the mission) and reach (sphere of influence) - combine into "gravity".
Strong when: the journey is community-shaped and depth of relationship matters more than a purchase. Weak as a whole-journey model for a commercial product, because it says nothing about evaluation or production use.
### 4. API and platform five-stage arc
Awareness → onboarding → integration → production → advocacy.
Carried by the `gtm-developer-ecosystem` skill (beingsmit/technical-product-gtm). Its stages are useful; its published numbers are one company's anecdotes and must never be quoted as benchmarks.
Strong when: the product is an API or SDK and the real conversion is "running in production", which the commercial models tend to hide inside retention.
### 5. OSS contributor funnel
Land → find work → set up → change → submit → survive review → return.
Consolidated from GitHub's Open Source Guides and the newcomer-barriers research literature. Two steps leak hardest and leak silently: local setup, and waiting for review. GitHub's Open Source Guides report that contributors who received code review within 48 hours had a much higher rate of return and repeat contribution, and that "it only takes one negative experience to make someone not want to come back".
Strong when: the desired end state is contribution. Use it as the whole model for an OSS project, or as an expansion of a single "contribute" stage inside another model.
## Choosing between them
| If the end state is… | Use | Terminal stage |
| ------------------------------------ | ---------------------- | --------------- |
| an organisation defaults to the tool | Revell six-stage | standardization |
| paid conversion and expansion | AAARRRP | revenue |
| deep community relationships | Orbit levels | advocate |
| workloads running in production | API five-stage arc | production |
| sustained outside contribution | OSS contributor funnel | return |
That table deletes rather than ranks: a model whose terminal stage is not the funded end state leaves the menu. The ranked comparison of what survives lives in the skill's step 1; the effort notes below only feed it.
Secondary criteria, in order:
1. **Observability.** Prefer the model whose stage boundaries you can already see in data you hold. This is the effort axis, and it decides the ranking in step 1.
2. **Ownership.** Prefer boundaries that fall on team lines, so each stage gets one accountable owner instead of a committee.
3. **Continuity.** If a previous map exists, keep its model unless it broke - comparability against your own history is worth more than a better-fitting vocabulary.
Effort to stand each one up, in orders of magnitude - evidence needed before a boundary can be counted:
| Model | Effort | What makes it cost that |
| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| API five-stage arc | an hour to a week | first call, integration and production usually already sit in product telemetry |
| OSS contributor funnel | a week | the repository holds first PR, review latency and return; recruiting abandoners is the slow part |
| AAARRRP | a week to a quarter | mostly coordination: its stages must reconcile with a company-wide funnel another team owns |
| Revell six-stage | a quarter | the standardisation boundary needs account rollup and buyer-side interviews almost nobody holds |
| Unsourced default | near-zero | nothing to reconcile - and it buys no comparability, which is why cheapest is not first |
## The unsourced default
Discover → try → adopt → contribute → advocate is the shorthand many teams start from. It is a merge of models 3, 4 and 5 rather than a framework anyone published. It works as a working spine for a first map, and it is honest to use - as long as nobody presents it as a framework, and as long as the "adopt" stage gets split once it becomes clear it hides both integration and production.
## Why the tails disagree
The models agree on the start and diverge after adoption because they were built for different desired outcomes:
- Revell ends where an organisation commits.
- AAARRRP ends at money plus product feedback.
- Orbit and the contributor funnel end where an individual takes on work for the project.
A map keeping all three tails has three terminal stages and therefore no priority order. Choose the tail that matches what funds the program, and demote the others to optional branches drawn under the main line.
## What the map has to add
Stage owners, and the exit event that proves a developer left one stage for the next, come from the map rather than from a stage model: the models stop at vocabulary. Revell's guide closed by promising per-stage measurement in a future guide that never followed, which is a fair summary of the field's state - the journey vocabulary is settled, per-stage measurement is not. Those columns are the map's real work and have to be derived per product.
SKILL.md›
---
name: developer-journey-map
description: Maps the developer journey for one audience segment - discovery, trial, adoption, contribution, advocacy - as a stage-by-stage table where each stage carries an exit event, a named owner, cited friction evidence and one signal, and names the single leak worth fixing next. Use whenever someone asks what their developer journey looks like, wants a developer adoption funnel or journey map, asks why developers try the product but never reach production, where adoption drops off, who owns each step of developer experience, or how developers become contributors - even if they only say "we lose people somewhere". Not the metrics framework - use samber/developer-relations-skills@devrel-metrics.
license: MIT
metadata:
author: Samuel Berthe
version: "1.0.1"
---
# 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.
## 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](./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.
## Invocation examples
| The user says | What 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
## 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.
**Memory: Store a few info about the current task or project context. When memory lives in a file, use `devrel-context.md`; if a different memory system is in use, rely on that instead. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.**
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.
## Step 1 - Choose the stage model, do not invent one
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](./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.
## Step 2 - Collect evidence before filling any row
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](./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.
## Step 3 - Fill one row per stage
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.
| Field | What goes in it |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Stage | the name from the chosen model |
| Developer's job | what the person is trying to accomplish, in their words, not the vendor's funnel language |
| Entry trigger | the observable event that starts the stage |
| **Exit event** | the single observable event proving they moved on - first successful API call, first deploy to production, first merged PR, first talk given |
| Touchpoints | the surfaces involved: docs page, repo, CLI output, dashboard, community thread, support ticket |
| **Owner** | one person or team accountable for this stage's exit rate |
| Friction evidence | a cited observation with its source, never a hypothesis; write "no evidence yet" when there is none |
| **Signal** | one 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.
## Step 4 - Add the buyer lane, or say there isn't one
- **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.
## Step 5 - Name the three critical moments
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.
## Step 6 - Diagnose the leak
- 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.
## Step 7 - Write the map and validate it section by section
```markdown
# 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
```
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).
## 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.
## 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.
## References
- [references/stage-models.md](./references/stage-models.md) - the published stage models, their sources, and how to pick one.
- [references/evidence-and-signals.md](./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](./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](./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.