Developer Experience: Diagnose Friction Before Building a Platform

Diagnose a developer workflow using task observation, focused survey questions and system evidence. Includes a preview-environment example and a platform pilot worksheet.

Follow one frustrating task

Before funding a developer portal, watch someone perform a recurring task: run a service locally, create a preview environment, understand a failed test or restore a deployment. Record where they wait, search, ask another person or repeat work.

A tool can be fast while the workflow is slow. An environment might provision in minutes but remain unusable until someone grants access and explains a missing configuration. Optimizing provisioning alone leaves that delay intact.

This guide focuses on diagnosing friction and shaping a bounded platform improvement. For defining comparison groups, denominators and outcome interpretation, use the productivity measurement experiment guide.

Use the DevEx framework accurately

The 2023 paper DevEx: What Actually Drives Productivity, by Abi Noda, Margaret-Anne Storey, Nicole Forsgren and Michaela Greiler, organizes developer experience around feedback loops, cognitive load and flow state.

Use those dimensions to ask different questions. Feedback concerns the speed and usefulness of a response. Cognitive load concerns the effort needed to understand and complete work. Flow concerns the ability to sustain focused engagement. Faster builds can help one part of the experience without fixing unclear ownership or constant interruptions.

The authors recommend combining developer feedback with information from systems. Neither a satisfaction score nor a deployment count explains a workflow on its own.

These concepts do not establish that a specific platform feature will reduce turnover or cause a fixed productivity gain. Test the local problem and the proposed change. Retention, product outcomes and engineering experience have other influences that a short pilot cannot isolate.

Collect a useful friction report

Invite developers with different familiarity and support needs to describe a recent attempt. Ask permission before observing work and avoid recording source code, secrets or unrelated communications.

Use consistent, task-specific questions:

| Question | What the answer helps distinguish | |---|---| | What were you trying to complete, and how did you know it was done? | A usable outcome versus a tool reporting success. | | Where did you wait for a person or system? | Queue time versus execution time. | | Which step required information you could not find? | Missing documentation, unclear ownership or hidden prerequisites. | | When did you switch tasks, and what made returning difficult? | Interruptions and recovery effort. | | What failed, and could you understand the next action? | Diagnostic quality and support dependency. | | Which part would you change first? | User priorities, including problems absent from telemetry. |

Keep “not applicable” and “prefer not to answer” available in a survey. For recurring questions, keep wording and the reference period stable so changes are interpretable.

A low response rate or an enthusiastic volunteer group can distort the picture. Report who was invited, how many responded and which workflow they used, while protecting identities. Small groups and free-text comments can identify people even after names are removed.

The SPACE publication cautions against reducing productivity to one activity or dimension. Use that perspective to keep a friction survey from becoming an individual performance score.

Worked diagnosis: a preview environment

Consider a hypothetical developer validating a service change in an isolated preview environment. The following trace is an illustrative observation, not an Ampity engagement or an onboarding benchmark.

| Time | Observable event | |---|---| | 09:00 | Developer submits a complete preview request. | | 09:05 | The request reaches the approval queue. | | 10:20 | The authorized reviewer approves it. | | 10:28 | Provisioning finishes. | | 10:45 | The developer finds the missing setup instruction and completes the first useful check. |

Request-to-validation time is 105 minutes. The approval queue accounts for 75 minutes, provisioning for 8 minutes, and the period after provisioning for 17 minutes. The remaining 5 minutes precede the approval queue. These intervals sum to 105 minutes.

That trace does not measure 105 minutes of active developer effort. The developer may have worked on another task while waiting. Record elapsed time and hands-on effort separately.

The diagnosis should examine why approval waited. Perhaps the reviewer lacked context, the request was misrouted, or the action requires a necessary control. Removing approval without that investigation could introduce access or cost risk.

The missing setup instruction is a different problem. A clear completion check and a maintained setup page may address it without creating a new platform.

Turn the diagnosis into a pilot contract

The hypothetical pilot tests a supported request path for an already-approved class of isolated environments. The security and platform owners must define its permitted resources, identity scope, data restrictions and expiry. Requests outside that policy still use review.

The platform team also adds a readiness check and the missing setup instruction. Keep these as separately observable changes so the team can distinguish their effects.

| Pilot field | Agreement to complete | |---|---| | User and task | Which developers and service types need the preview workflow? | | Usable result | An authorized user can run the agreed validation against the intended revision. | | Baseline | Request-to-ready and request-to-validation distributions, failures and support interventions for comparable attempts. | | Proposed change | Correct routing or policy-backed self-service, plus clear setup and readiness information. | | Guardrails | No production data, unauthorized access, orphaned resources or hidden support burden. | | Evidence | Task completion, waiting by stage, support requests and repeated user questions. | | Stop and recovery | Disable the new path if controls fail; keep a supported manual request path. | | Owner | Named platform, security and application contacts for operation and review. |

This is a worksheet to fill with actual evidence. The example does not promise a target duration or assume every workflow should become self-service.

Build the smallest supported capability

The CNCF Platforms White Paper describes platforms as capabilities designed around internal users and emphasizes working with those users as product partners.

For the preview task, the useful capability includes the request interface, policy, provisioning, readiness signal, diagnostics, support and cleanup. A portal is only one possible interface. An existing command or repository workflow may fit better.

Keep responsibilities visible. Application teams own the behavior they are validating. The platform team owns the supported environment interface. Security owners approve access policy. Infrastructure providers may operate the underlying resources.

Make failures understandable. A rejected request should identify the violated constraint and the supported next step without disclosing sensitive configuration. A partially created environment needs cleanup or a resumable operation, not a second request that creates duplicate resources.

A standard path also needs an exception process. Forcing an unsupported workload through a template can move complexity into hidden scripts and emergency tickets.

Check whether the change helped

Compare equivalent task attempts, including failures and abandoned requests. Record changes in service type, experience level, approval policy and underlying infrastructure that could explain the result.

Repeat the specific survey questions after people have used the new path. Ask whether they can interpret failures and recover without help. A faster successful path can coexist with a worse failure experience.

Inspect both the common case and the tail. An average can improve while a smaller group remains unable to complete the task. Aggregate enough to protect individuals, and use confidential follow-up to understand gaps that cannot safely be reported as small-group statistics.

Report operating cost and support work too. A platform engineer manually repairing every request has not demonstrated dependable self-service. Expiring resources, maintaining templates and updating instructions are ongoing responsibilities.

Treat a before/after improvement as local evidence, not proof that the intervention alone caused it. Changes in workload, staffing or participant familiarity can affect the result.

Give developers a visible decision

Close the loop with a short record: the friction observed, change tested, evidence collected, remaining limitation and next decision. Keep, revise or stop the capability based on that evidence.

For a cloud platform engineering review, bring one task trace and the completed pilot worksheet. They make the scope concrete and show whether the next investment belongs in tooling, policy, documentation or ownership.