improve-developer-onboarding

name	improve-developer-onboarding
category	start
description	Shorten and strengthen the path from repository access to a verified first change by repairing setup, documentation, permissions, and feedback loops. Use when new developers stall, rely on oral knowledge, or cannot reproduce the supported environment.

improve-developer-onboarding

Treat onboarding as an executable product journey. Measure where a capable new contributor loses time, access, context, or confidence, then repair the system rather than blaming the person.

Inputs

• Gather onboarding docs, repositories, access paths, environments, build and test commands, and team conventions.
• Use recent onboarding notes, setup failures, support requests, and time-to-first-change evidence.
• Identify security, license, data, hardware, network, and platform constraints.

Procedure

1. Define the onboarding outcome as a clean setup, passing checks, and one reviewed representative change.
2. Map every prerequisite, request, wait state, owner, approval, and expected observation.
3. Run the current guide from a clean supported environment and log failures and hidden steps.
4. Separate mandatory access and knowledge from optional tools and historical context.
5. Create a repository map covering entry points, tests, local services, deployment boundaries, and owners.
6. Make setup commands deterministic, safe to rerun, and explicit about secrets and generated state.
7. Add a small first change that exercises the real edit, test, review, and feedback loop.
8. Document common failures with symptoms, diagnostics, and recovery.
9. Pilot with a new contributor without coaching and record time, blockers, and questions.
10. Assign owners and automated checks so the path stays current.

Boundaries

Do not share credentials, production data, broad access, or private employee information to make onboarding easier. Never require unsupported personal equipment or unpaid hidden work. Provide accessible and platform-appropriate alternatives.

Done

• A clean supported environment completes setup and the documented checks
• Required access, waits, owners, repository map, and common recovery paths are written
• A new contributor completed a representative first change and review from the guide
• Blockers, elapsed time, and follow-up improvements are recorded with owners