Designing Onboarding Journeys

Rule: First success must involve the product doing its core job, not just setup.

TTFS Targets

Journey Architecture

The Onboarding Spine

Every onboarding journey follows a spine — a linear sequence of milestones that the developer must reach:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  MILESTONE 0 │───▶│  MILESTONE 1 │───▶│  MILESTONE 2 │───▶│  MILESTONE 3 │
│  Environment │    │ First Success│    │  Core Loop   │    │  Production  │
│  Ready       │    │  (TTFS)      │    │  Mastered    │    │  Ready       │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
     │                   │                   │                   │
   Install            Hello World         Real workflow       Deploy, auth,
   Configure          Working example     Error handling      monitoring
   Authenticate       "It works!"         Customization       Scaling

Milestone Definitions

Progressive Complexity Curve

Each page in the journey adds exactly one new concept. The complexity curve should feel like a gentle ramp, not a staircase.

Complexity
    ▲
    │                                    ┌── M3: Production
    │                              ┌─────┘
    │                        ┌─────┘
    │                  ┌─────┘ M2: Core Loop
    │            ┌─────┘
    │      ┌─────┘
    │ ┌────┘ M1: First Success
    │─┘
    │ M0: Setup
    └──────────────────────────────────────▶ Pages

Complexity Budget Per Page:

Persona-Based Path Branching

Branch Point Design

After M1 (First Success), onboarding paths diverge based on developer persona:

                    ┌─────────────────┐
                    │  M1: First      │
                    │  Success         │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │ Backend  │  │ Frontend │  │ Full-Stack│
        │ Developer│  │ Developer│  │ Developer │
        └────┬─────┘  └────┬─────┘  └────┬─────┘
             │              │              │
        [API guides]  [SDK guides]   [Platform   ]
        [Webhooks  ]  [Components]   [  guides   ]
        [CLI tools ]  [Styling   ]   [Integration]
             │              │              │
             └──────────────┼──────────────┘
                            ▼
                    ┌─────────────────┐
                    │  M3: Production │
                    │  Ready          │
                    └─────────────────┘

Branch Point Implementation

Branch Card Template:

## Choose Your Path

You've completed the quickstart. Choose the guide that matches what you're building:

- **Build an API Integration** — Connect your backend to [Product] with REST or GraphQL
- **Add [Product] to Your Frontend** — Drop-in components for React, Vue, or Svelte
- **Deploy a Full Platform** — Set up [Product] as your complete [domain] solution

Page Sequencing Rules

Sequencing Principles

Handoff Patterns Between Page Types

Anti-Patterns in Sequencing

Milestone Placement

Milestone Signals

Each milestone must include visible confirmation that the developer has reached it:

Progress Indicators

Journey Map Template

## Onboarding Journey: {Product Name}

### Overview
- **Target TTFS**: {minutes}
- **Total pages**: {count}
- **Estimated total time**: {minutes}

### Spine

| # | Page | Type | Milestone | New Concept | Time | Prerequisites |
|---|------|------|-----------|-------------|------|---------------|
| 1 | Install & Configure | Quickstart | M0 | Setup | 3 min | None |
| 2 | Your First [Action] | Quickstart | M1 (TTFS) | Core API call | 5 min | Page 1 |
| 3 | [Branch Point] | Routing | — | — | 1 min | Page 2 |
| 4a | Build [Path A] | How-To | — | [Concept A] | 10 min | Page 2 |
| 4b | Build [Path B] | How-To | — | [Concept B] | 10 min | Page 2 |
| 5 | [Core Workflow] | How-To | M2 | [Concept] | 10 min | Page 4a or 4b |
| 6 | Deploy to Production | How-To | M3 | Deploy config | 15 min | Page 5 |

### Persona Paths

| Persona | Path | Pages | Total Time |
|---------|------|-------|------------|
| {Persona A} | 1 → 2 → 3 → 4a → 5 → 6 | 6 | 44 min |
| {Persona B} | 1 → 2 → 3 → 4b → 5 → 6 | 6 | 44 min |

### Prerequisite Graph

Page 1 → Page 2 → Page 3 → Page 4a ──┐
                          └─→ Page 4b ──┼─→ Page 5 → Page 6

Audit Checklist

TTFS Optimization

• First Success is defined as the product doing its core job (not just setup)
• TTFS target is set appropriate to product complexity tier
• Steps to first success are within budget (5/10/15 by tier)
• No concepts-only pages before M1

Journey Structure

• Onboarding spine has exactly 4 milestones (M0-M3)
• Each page introduces exactly 1 new concept
• Each page builds on the output of the previous page
• Each page ends with verification before linking to next
• No circular dependencies in prerequisite graph
• No dead-end pages (every page has Next Steps)

Progressive Complexity

• Complexity curve is a gentle ramp, not a staircase
• No page requires more than 1-2 new API calls/methods
• Setup is minimized to 1 page before first success
• Optional configuration is deferred past M1

Persona Branching

• Branch point appears after M1, not before
• 2-4 branch paths (not more)
• Branch labels describe what to build, not who the user is
• Most common path is highlighted as recommended
• All paths converge at M3

Handoff Quality

• Quickstart → How-To handoffs reference the artifact built
• How-To → How-To handoffs build on the same artifact
• Reference links appear inline when parameters are mentioned
• Explanation links appear in callout boxes, not required to proceed
• Time estimates appear on every page

Output Format

Onboarding Journey Design: {product or scope}

TTFS Target: {minutes} | Complexity Tier: {Simple/Medium/Complex}

Journey Spine:

Persona Paths: {count} paths from branch point

Issues Found:

• {issue and recommendation}

Proposed Sequence:

{Journey map with page sequence and handoff patterns}

Guidelines

• DO: Define First Success before designing any pages — it's the anchor for the entire journey
• DO: Keep the path from M0 to M1 as short as possible — front-load the dopamine hit
• DO: Use verification sections as milestone signals — developers need confirmation they're on track
• DO: Design branch points as self-selection cards with build-oriented labels
• DON'T: Front-load concepts — lead with action, explain as needed
• DON'T: Branch before M1 — every developer needs the same First Success
• DON'T: Create dead-end pages — every page must link forward
• DON'T: Skip time estimates — they set expectations and reduce abandonment

Related Components

• scaffolding-page-archetypes skill: Defines the structural anatomy of individual page types this skill sequences
• designing-landing-pages skill: Handles the landing page entry point; Getting Started Block previews the journey this skill designs
• auditing-docs-metrics skill: TTFS is a key metric this skill optimizes for
• governing-docs-lifecycle skill: Pages in the journey follow lifecycle states defined there
• docs-designer agent: Ensures individual pages in the journey meet quality standards
• page-scaffolder agent: Generates individual pages that this skill sequences into a journey