Onboarding¶
OWNER: aimee ALSO_USED_BY: anna (implementation), faye, sytske
63% of customers consider onboarding a deciding factor when subscribing. 75% of new users abandon within the first week without effective onboarding. Every extra minute to first value lowers conversion by 3%.
Target: under 2 minutes to first perceived value. Under 15 minutes to full activation.
Onboarding Architecture¶
SCOPE_ITEM: onboarding_flow
Phase 1: Signup (< 30 seconds)¶
INCLUDES: Signup form with maximum 3 fields (name, email, password) INCLUDES: Social signup (Google, Microsoft) as single-click alternative INCLUDES: Email verification deferred — verify AFTER user is inside the app INCLUDES: No credit card required for trial or free tier INCLUDES: Org creation inline during signup (org name auto-suggested from email domain) CHECK: Every extra signup field costs ~7% conversion — ruthlessly minimize CHECK: Email verification before app access is a conversion killer — defer it
Phase 2: Setup Wizard (< 2 minutes)¶
INCLUDES: 3-5 step guided wizard after first login INCLUDES: Progress indicator (step X of Y) INCLUDES: Skip button on every step (can resume later) INCLUDES: Wizard state persisted — user can leave and return
Typical wizard steps:
Step 1: Organization profile (name, logo upload, timezone) — pre-filled from signup
Step 2: Use case selection (personalizes dashboard and feature exposure)
Step 3: Invite teammates (email input, skip option)
Step 4: Connect integrations (top 3 most popular, skip option)
Step 5: Import data OR apply template (mutually exclusive, skip option)
CHECK: Steps must be domain-specific — customize for each client's product CHECK: Pre-fill everything possible (email domain → org name, geo → timezone) CHECK: Skip option is mandatory — forced completion causes abandonment
Phase 3: First Value ("Aha Moment") (< 5 minutes)¶
INCLUDES: Guided first action after wizard completes INCLUDES: Context-aware tooltip highlighting the primary CTA INCLUDES: Pre-loaded demo data if user skipped import (nobody likes empty screens) INCLUDES: Success celebration on first completed action (subtle, not annoying) CHECK: Define the "aha moment" per product during scoping — what is the first thing that makes the user say "this is useful"?
Phase 4: Activation (< 7 days)¶
INCLUDES: Onboarding checklist in sidebar or dashboard (persistent, dismissable) INCLUDES: Drip email sequence (day 1, 3, 5, 7) highlighting unfinished setup tasks INCLUDES: In-app nudges for unvisited core features INCLUDES: Teammate activity triggers ("your colleague just created a project") CHECK: Activation = setup complete + core action taken + value perceived CHECK: Track activation rate — benchmark is 37.5% average, target > 50%
Data Import¶
SCOPE_ITEM: data_import_onboarding
CSV Import¶
INCLUDES: Upload CSV file (drag-and-drop or file picker) INCLUDES: Auto-detect column headers and data types INCLUDES: Column mapping UI (source column → target field, with auto-suggestions) INCLUDES: Preview first 10 rows before committing INCLUDES: Validation with row-level error reporting INCLUDES: Async processing for files > 1000 rows (progress bar, email on completion) INCLUDES: Error report downloadable as CSV (row number, field, error description) INCLUDES: Duplicate detection (configurable: skip, overwrite, create new) CHECK: CSV import is the #1 onboarding blocker — invest 30-50 hours here CHECK: Support UTF-8, Latin-1, and Excel-exported CSV (BOM handling) CHECK: Maximum file size: 50MB (configurable per plan)
API-Based Import¶
INCLUDES: Import from competitor API (if reverse-engineering is allowed) INCLUDES: OAuth2 connection to source system INCLUDES: Data mapping between source and target schemas INCLUDES: Incremental sync (not just one-time import) OPTIONAL: Pre-built importers for common competitors in the vertical CHECK: API import adds 40-80 hours per source system — prioritize top 2-3
Concierge Import¶
INCLUDES: "Send us your spreadsheet" upload form INCLUDES: Internal queue for GE or client's team to process manually INCLUDES: Status tracking for the customer (submitted, processing, complete) OPTIONAL: Automated pipeline with manual review step CHECK: 40% of users prefer concierge import — offer it even if self-serve exists CHECK: Concierge import is an operations cost, not a dev cost — clarify with client
Demo Data¶
INCLUDES: Pre-loaded realistic demo data per use case INCLUDES: Demo data clearly labeled ("Sample Project — delete anytime") INCLUDES: One-click "remove all demo data" action INCLUDES: Demo data covers all major entity types (shows full product capability) CHECK: Nobody likes an empty dashboard — always offer demo data as fallback CHECK: Demo data must be domain-appropriate (not "Lorem ipsum" placeholders)
Starter Templates¶
SCOPE_ITEM: starter_templates INCLUDES: Pre-built workspace templates for common use cases INCLUDES: Template gallery with descriptions and previews INCLUDES: One-click "apply template" creates pre-configured workspace INCLUDES: Template includes: structure, sample data, default settings, automations OPTIONAL: Community templates (user-submitted, moderated) OPTIONAL: Industry-specific templates (e.g., "Consulting Agency", "E-commerce Ops") CHECK: Templates reduce time-to-value by 40-60% — always include 3-5 templates CHECK: Templates must be maintained — stale templates erode trust
Product Tours¶
SCOPE_ITEM: product_tours INCLUDES: First-use tooltips on key UI elements (5-7 tips max) INCLUDES: Tooltip sequence follows natural workflow order INCLUDES: Dismissable individually or all at once INCLUDES: Completion state persisted (never show completed tips again) INCLUDES: "Restart tour" option in help menu OPTIONAL: Interactive walkthrough (user performs action with guided overlay) OPTIONAL: Video embed for complex features (< 60 seconds each) CHECK: Tooltips are cheap (5-10 hours). Interactive walkthroughs are expensive (30-50 hours). CHECK: Do not tooltip everything — focus on the critical path to activation
Trial-to-Paid Conversion¶
SCOPE_ITEM: trial_conversion INCLUDES: Trial duration: 14 days (standard) or 30 days (complex products) INCLUDES: Trial includes full feature access (or tier-specific trial) INCLUDES: Trial countdown visible but not obnoxious (settings page, not banner) INCLUDES: Trial expiry warnings: 7 days, 3 days, 1 day, expired (email + in-app) INCLUDES: Upgrade CTA prominent but not blocking during trial INCLUDES: Post-expiry: read-only access (data preserved, cannot create/edit) INCLUDES: Reactivation: any time within 90 days, data intact OPTIONAL: Trial extension (manual, triggered by sales or support) OPTIONAL: Exit survey on trial expiry without conversion CHECK: Trial-to-paid target: > 15% self-serve, > 25% sales-assisted CHECK: If conversion < 10%, onboarding is broken — fix before scaling acquisition
Conversion Optimization Signals¶
IF: User completed setup wizard but did not take core action THEN: Send targeted email highlighting the core action with direct link IF: User is active but has not invited teammates THEN: In-app prompt: "Invite your team to get the most out of [product]" IF: User is active, has teammates, approaching trial end THEN: Send case study email + upgrade CTA IF: User has not logged in for 3+ days during trial THEN: Re-engagement email: "We noticed you haven't been back — here's what's new"
Activation Metrics¶
SCOPE_ITEM: activation_metrics
Key Metrics to Track¶
| Metric | Definition | Benchmark | Target |
|---|---|---|---|
| Signup-to-login rate | % of signups that actually log in | 80% | > 90% |
| Wizard completion rate | % that complete setup wizard | 60% | > 75% |
| Time to first value | Time from signup to first core action | Varies | < 5 min |
| Activation rate | % reaching activation milestone | 37.5% avg | > 50% |
| Day-1 retention | % that return on day 2 | 40% | > 50% |
| Day-7 retention | % that return within first week | 25% | > 35% |
| Trial-to-paid | % of trials converting to paid | 15% avg | > 20% |
| Core feature adoption | % using primary feature | 24.5% avg | > 40% |
Defining the Activation Milestone¶
The activation milestone is product-specific. Define it during scoping.
IF: Collaboration product THEN: Activation = invited 1+ teammate AND created 1+ shared item IF: Data/analytics product THEN: Activation = imported data AND viewed 1+ report IF: Workflow/automation product THEN: Activation = created 1+ workflow AND it ran successfully IF: Communication product THEN: Activation = sent 1+ message in a shared channel
CHECK: Analyze behavior of users who became paying customers — find the common early actions CHECK: A 25% increase in activation yields ~34% increase in MRR within 12 months
Implementation Notes¶
SCOPE_ITEM: onboarding_implementation
State Tracking¶
INCLUDES: Table `onboarding_state` — user_id, tenant_id, wizard_completed, wizard_step, checklist_items (JSONB), activated_at, activation_milestone
INCLUDES: Checklist items tracked individually (completed, skipped, dismissed)
INCLUDES: Analytics events fired for each onboarding step (signup, wizard_start, wizard_step_N, wizard_complete, first_action, activated)
Email Sequences¶
INCLUDES: Welcome email (immediate after signup)
INCLUDES: Setup reminder (day 1, if wizard not completed)
INCLUDES: Feature highlight (day 3)
INCLUDES: Teammate invite prompt (day 5)
INCLUDES: Trial ending warning (day 7 before expiry)
INCLUDES: Trial expiry (on expiry date)
INCLUDES: Post-expiry win-back (7 days after expiry)
CHECK: Email sequence is a growth lever — personalize by use case and progress CHECK: Unsubscribe link mandatory on all non-transactional emails