| name | designing-developer-onboarding |
| description | Designs developer onboarding experiences and documentation sequences. Use when creating getting-started guides, quickstart flows, developer portals, sandbox environments, or progressive learning paths for APIs and platforms. |
Designing Developer Onboarding
Quick start
Collect or infer:
- Platform/API being onboarded to
- Target developer persona (hobbyist, enterprise, specific stack)
- Time-to-first-success target (minutes to working example)
- Authentication and access requirements
- Available sandbox/test environments
Then produce output using TEMPLATES.md. Validate with RUBRIC.md.
Workflow
- Define the "aha moment": what working state proves the platform's value?
- Map prerequisites: account creation, credentials, environment setup.
- Design the fastest path to first success (strip non-essential steps).
- Identify natural expansion points after initial success.
- Create progressive complexity tiers: quickstart → tutorial → reference.
- Build escape hatches for stuck developers.
- Add measurement points to track onboarding completion.
- Run the rubric check. Revise until it passes.
Degrees of freedom
Medium freedom
- Default: follow templates for onboarding structure
- Allowed variation: progression depth may vary by platform complexity; persona-specific paths permitted; sandbox requirements differ by platform
State awareness
Developer onboarding tracks through states:
- Unaware: Hasn't heard of platform
- Curious: Evaluating, needs clear value proposition
- Committed: Signed up, needs fast first success
- Exploring: First success achieved, expanding usage
- Integrating: Building production implementation
- Stuck: Encountered obstacle, needs rescue path
References
