# Developer Journey Atlas methodology

The Atlas publishes only a selected account-creation-to-first-success route that passes deterministic platform identity, first-party source-content, claim-grounding, required-field, branch, and route-integrity gates. Documentation structure is not evidence of usability, conversion, abandonment, difficulty, or causality.

# Shortest required path selection policy

Date: 2026-07-21

## Boundary

Every audited journey begins at account creation and ends at the earliest meaningful first-success outcome established by current official evidence.

The account, tenant, credentials, product resources, connected repositories, legal acceptance, and permissions do not exist at the start unless the developer goal explicitly names a prior artifact, such as an existing Git repository to deploy.

## Selected surface

Use the platform's self-service web onboarding surface when one exists. Do not replace the product flow with a CLI, coding agent, infrastructure template, or third-party automation unless the selected developer goal explicitly requires that surface or no self-service path exists.

## Shortest-path rule

Reconstruct complete official candidate routes to the same outcome, then select lexicographically:

1. Prefer a route without payment, administrator work, manual approval, or unavailable entitlement.
2. Minimize required developer actions.
3. When tied, prefer fewer unavoidable waits and fewer external-system handoffs.
4. When still tied, prefer the vendor's documented recommended, quickstart, default, or first route.
5. If a consequential tie remains, do not invent a winner. Mark the audit `needs-human-judgment`.

No opaque weighted friction score is used.

## Units

- A required action is one developer interaction or implementation action that changes state.
- A required field is tracked under the form action that contains it and counted separately.
- Documentation reading, optional work, platform automation, and passive waiting are not developer actions.
- Required agreements, verifications, permissions, and external authorizations are included.
- Platform automation and waits remain visible in their own fields.

## Publication gate

The preserved source records in `records/` are evidence archives. A record is not a verified shortest path until a matching audit in `audits/` passes `shortest-path-audit.schema.json`, source-hash checks, evidence-reference checks, and cold or independent review.

Only audits marked `verified` may expose action counts or peer comparison. All others must show their exact status and evidence gap.

# Measurement contract (v2.0)

## What this corpus contains

Developer Journey Atlas has two layers:

1. `records/` preserves detailed official-documentation evidence collected under the original research method.
2. `audits/` reconstructs the verified shortest required developer path from account creation to first success.

A source record does not become a verified path merely because it validates. Public counts and comparisons come only from verified audit records.

This is documentation and public-interface research. It is not telemetry, conversion, activation, drop-off, usability, or observed completion time.

## Required developer action

One intentional interaction or implementation action performed by the developer before first success.

Examples:

- submit the account-creation form;
- authorize repository access in GitHub;
- choose `New > Web Service`;
- install a dependency;
- add required code;
- run a command;
- open the terminal result.

Documentation reading, research-route selection, platform automation, and optional work are excluded.

## Required field

One required input, checkbox, agreement, challenge, permission, URL, repository, command value, or other field contained in a required action.

Fields are listed under their form or interaction and counted separately. A seven-field service form is one journey action and seven required fields. This prevents both hiding field burden and inflating the journey into one step per HTML control.

## External gate

A required permission, administrator action, entitlement, payment, legal acceptance, identity-provider authorization, or other boundary outside the platform's direct control.

The developer interaction may appear in the path. The gate itself is counted separately.

## Unavoidable wait

A required asynchronous interval such as email delivery, provisioning, build, deployment, or human approval.

Passive waiting is not a developer action. A separate developer action is counted only when the developer must interact again to continue.

## Platform outcome

Automatic work performed by the platform or an external system, such as generating credentials, running a build, returning an API response, or marking a deploy Live.

Platform outcomes remain visible but are never counted as developer actions.

## First success

The earliest meaningful observable result explicitly named or demonstrated by the selected official getting-started route. Resource creation or credential visibility alone is not enough unless the official route defines it as the terminal developer result.

## Comparisons

Anonymous peer context is withheld unless:

- the subject and every peer have verified shortest-path audits;
- the source research is marked complete;
- all routes begin at account creation;
- category and normalized first-success type match;
- research granularity and comparability metadata are compatible;
- at least three qualified peers remain.

The comparison may show direct medians for required actions, required fields, unavoidable waits, and external gates. It must not combine them into a difficulty, quality, or drop-off score.

## Legacy measurements

`selected-path-heuristic.json`, `ds-quality.json`, and original source-record step counts remain in the repository for provenance and migration analysis. They are not public shortest-path measurements and must not power user-facing claims.