developer-onboarding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Developer Onboarding

开发者入职

Get developers from signup to working code as fast as possible, then guide them to deeper engagement.

让开发者从注册到写出可运行代码的流程尽可能顺畅，进而引导他们进行更深度的使用。

Overview

概述

Developer onboarding is the critical window between "I signed up" and "I understand how to use this." You have about 10 minutes of developer attention. Every second of confusion, every error message without guidance, every "it should work but doesn't" moment costs you users.

Great onboarding feels like pair programming with someone who anticipated every question. Bad onboarding feels like being dropped in a foreign city without a map.

开发者入职是介于「我完成注册」和「我知道怎么用这个工具」之间的关键阶段，你大概只有10分钟的开发者注意力窗口期。每一秒的困惑、每一条没有指导的错误提示、每一次「按理应该能跑但就是不行」的时刻，都会让你流失用户。

优秀的入职体验就像和一位提前预判了你所有问题的人结对编程，糟糕的入职体验就像被扔到一个陌生城市却没有地图。

Before You Start

开始之前

Review the

/devmarketing-skills/skills/developer-audience-context

skill to understand your target developers. A hobbyist building side projects needs different onboarding than an enterprise architect evaluating tools for production. Review

/devmarketing-skills/skills/developer-signup-flow

to ensure signup flows smoothly into onboarding.

请先查阅

/devmarketing-skills/skills/developer-audience-context

技能文档，了解你的目标开发者群体：做业余项目的爱好者和为生产环境评估工具的企业架构师，需要的入职流程完全不同。同时查阅

/devmarketing-skills/skills/developer-signup-flow

文档，确保注册流程可以平滑过渡到入职阶段。

Time-to-First-Value Optimization

首次价值实现时间（TTFV）优化

Defining "First Value"

定义「首次价值」

First value isn't "made an API call." First value is when the developer sees your tool doing something useful for them.

Tool Type	First Value Moment
API	Response returns meaningful data
SDK	Library performs expected function
Database	Query returns results
Hosting	App is live and accessible
Auth	User successfully logs in
Payment	Test charge processes

首次价值不是「完成了一次API调用」，而是开发者切实看到你的工具为他们解决了某个实际问题的时刻。

工具类型	首次价值节点
API	接口返回有意义的数据
SDK	库执行了预期的功能
数据库	查询返回结果
托管服务	应用上线可访问
鉴权服务	用户成功登录
支付服务	测试支付流程完成

Measuring Time to First Value (TTFV)

衡量首次价值实现时间（TTFV）

Track timestamps at each stage:

signup_completed: 2024-01-15T10:00:00Z
dashboard_loaded: 2024-01-15T10:00:05Z
api_key_copied: 2024-01-15T10:01:30Z
first_api_call: 2024-01-15T10:04:45Z
first_successful_response: 2024-01-15T10:04:46Z  # TTFV = 4:46

Benchmarks by category:

Simple APIs: <5 minutes
SDKs requiring installation: <10 minutes
Complex infrastructure: <30 minutes
Self-hosted: <60 minutes

追踪每个阶段的时间戳：

signup_completed: 2024-01-15T10:00:00Z
dashboard_loaded: 2024-01-15T10:00:05Z
api_key_copied: 2024-01-15T10:01:30Z
first_api_call: 2024-01-15T10:04:45Z
first_successful_response: 2024-01-15T10:04:46Z  # TTFV = 4分46秒

不同品类的基准值：

简单API：<5分钟
需要安装的SDK：<10分钟
复杂基础设施：<30分钟
自托管服务：<60分钟

Removing TTFV Obstacles

清除TTFV阻碍

Map every step and eliminate blockers:

Common TTFV killers:

Email verification before dashboard access
API keys hidden in account settings
Quickstart assumes dependencies already installed
First example requires paid features
Error messages without resolution guidance
Docs search finds outdated tutorials

TTFV audit process:

Create new account (fresh browser, no cookies)
Screen record your first 30 minutes
Note every moment of confusion or friction
Time each step
Repeat with 5 different developer personas

梳理每个步骤，消除所有卡点：

常见的TTFV杀手：

必须完成邮箱验证才能访问控制台
API密钥隐藏在账户设置深层菜单
快速入门默认用户已经安装了所有依赖
第一个示例需要付费功能才能运行
错误提示没有附带解决方案
文档搜索返回的是过时教程

TTFV审计流程：

注册新账户（使用全新浏览器，无Cookie）
录屏记录你前30分钟的操作
记录每一次困惑或卡顿的时刻
统计每个步骤耗时
用5种不同的开发者 persona 重复上述流程

Quickstart Checklist Design

快速入门检查清单设计

The Ideal Quickstart Structure

理想的快速入门结构

markdown

undefined

markdown

undefined

Quickstart: [Specific Goal] in 5 Minutes

快速入门：5分钟实现[具体目标]

What you'll build: [Screenshot or description of end result]

Prerequisites:

Node.js 18+ (check: node --version)
npm or yarn

你将搭建的内容：[最终效果的截图或描述]

前置要求：

Node.js 18+（检查命令：node --version）
npm 或 yarn

Step 1: Install the SDK

步骤1：安装SDK

[One command, copy button]

[单条命令，附带复制按钮]

Step 2: Initialize with your API key

步骤2：用你的API密钥初始化

[Code with placeholder, copy button]

[带占位符的代码，附带复制按钮]

Step 3: Make your first request

步骤3：发起第一次请求

[Complete working example, copy button]

[完整可运行的示例，附带复制按钮]

Step 4: See the result

步骤4：查看结果

[Expected output shown]

[展示预期输出]

Next steps

后续步骤

[Link to common second task]
[Link to full documentation]

undefined

[链接到常见的第二个操作]
[链接到完整文档]

undefined

Checklist Patterns That Work

有效的清单模式

Progress indicators (Stripe style):

Your integration progress:
[x] Create account
[x] Get API keys
[ ] Install SDK
[ ] Make first API call
[ ] Handle webhooks

Contextual next steps (Vercel style):

You've deployed your first site.

What's next?
[ ] Add a custom domain
[ ] Set up environment variables
[ ] Enable analytics

进度指示器（Stripe风格）：

你的集成进度：
[x] 创建账户
[x] 获取API密钥
[ ] 安装SDK
[ ] 发起第一次API调用
[ ] 处理webhook

上下文关联的后续步骤（Vercel风格）：

你已经成功部署了第一个站点。

接下来可以做什么？
[ ] 添加自定义域名
[ ] 配置环境变量
[ ] 开启分析功能

Common Quickstart Failures

常见的快速入门错误

Too much context upfront:

undefined

前置冗余信息过多：

undefined

Bad: The history of authentication

反面例子：先讲鉴权的历史

Before we begin, let's understand OAuth 2.0... [500 words of background]

开始之前，我们先来了解OAuth 2.0的原理... [500字的背景介绍]

Good: Jump to action

正面例子：直接切入操作

Install the SDK and make your first authenticated request.


**Assuming environment:**

安装SDK，发起你的第一次鉴权请求。


**默认用户的环境配置统一：**

Bad

反面例子

Run

npm install

to install dependencies.

运行

npm install

安装依赖。

Good

正面例子

npm install our-sdk

Or with yarn: yarn add our-sdk

用yarn安装：yarn add our-sdk

Or with pnpm: pnpm add our-sdk

用pnpm安装：pnpm add our-sdk


**Hidden prerequisites:**


**隐藏前置要求：**

Bad (prerequisite discovered in Step 3)

反面例子（前置要求到第3步才出现）

Step 3: Connect to Redis First, make sure Redis is running...

步骤3：连接Redis 首先，确保Redis已经在运行...

Good (prerequisites listed upfront)

正面例子（前置要求提前列出）

Prerequisites:

Redis 6+ running locally (docker run -p 6379:6379 redis)

undefined

前置要求：

Redis 6+ 本地运行（启动命令：docker run -p 6379:6379 redis）

undefined

Interactive vs Static Tutorials

交互式教程 vs 静态教程

When to Use Interactive Tutorials

什么时候用交互式教程

Interactive tutorials work for:

Complex setup sequences
Concepts that benefit from immediate feedback
Onboarding flows where you control the environment
Features requiring API keys or credentials

Interactive tutorial tools:

Embedded code editors (CodeSandbox, StackBlitz)
Terminal emulators (Instruqt, Killercoda)
In-dashboard walkthroughs (Appcues, Pendo)
Interactive notebooks (Jupyter, Observable)

交互式教程适合这些场景：

复杂的配置流程
需要即时反馈才能理解的概念
你可以控制环境的入职流程
需要用到API密钥或凭证的功能

交互式教程工具：

嵌入式代码编辑器（CodeSandbox、StackBlitz）
终端模拟器（Instruqt、Killercoda）
控制台内引导（Appcues、Pendo）
交互式笔记本（Jupyter、Observable）

When Static Documentation Wins

什么时候用静态文档更优

Static docs work better for:

Reference documentation
Copy-paste code snippets
Steps involving local development
Content that changes frequently

静态文档更适合这些场景：

参考类文档
可复制粘贴的代码片段
涉及本地开发的步骤
频繁更新的内容

Hybrid Approach

混合方案

Best practice: Offer both

undefined

最佳实践：两种形式都提供

undefined

Make Your First API Request

发起你的第一次API请求

Quick version (copy-paste)

快速版本（复制粘贴即可运行）

[Code block with copy button]

[带复制按钮的代码块]

Interactive version

交互式版本

[Launch in StackBlitz] [Try in CodeSandbox]

[在StackBlitz中打开] [在CodeSandbox中试用]

Video walkthrough

视频演示

[5-minute embedded video]

undefined

[5分钟嵌入式视频]

undefined

Interactive Tutorial UX Guidelines

交互式教程UX指南

Do:

Save progress automatically
Allow skipping ahead
Show estimated time remaining
Provide escape hatch to static docs
Work in mobile browsers (at least for viewing)

Don't:

Require account creation for tutorials
Auto-play videos
Lock content behind completed steps
Time out idle sessions without warning
Require specific IDE or browser

推荐做法：

自动保存进度
允许跳过步骤
展示预计剩余时间
提供跳转到静态文档的出口
适配移动端浏览器（至少支持浏览）

不推荐做法：

要求先注册账户才能查看教程
自动播放视频
未完成前置步骤就无法查看后续内容
空闲会话无预警超时
要求使用特定IDE或浏览器

Sample Apps and Templates

示例应用和模板

Template Strategy

模板策略

Tiered approach:

Minimal example (Hello World)
- Single file
- Zero dependencies beyond your SDK
- Works in 30 seconds
- Purpose: Prove the SDK works
Starter template (Basic app)
- Simple folder structure
- Common patterns demonstrated
- Works in 5 minutes
- Purpose: Starting point for real projects
Production template (Full app)
- Production-ready architecture
- Auth, error handling, testing included
- Works in 30 minutes
- Purpose: Reference implementation

分层方案：

最小示例（Hello World级）
- 单文件
- 除了你的SDK之外零依赖
- 30秒内即可运行
- 目标：证明SDK可用
启动模板（基础应用级）
- 简单的文件夹结构
- 展示通用使用模式
- 5分钟内即可运行
- 目标：作为实际项目的启动基础
生产级模板（完整应用级）
- 生产可用的架构
- 包含鉴权、错误处理、测试配置
- 30分钟内即可运行
- 目标：参考实现

Template Organization

模板组织方式

github.com/your-org/
├── examples/
│   ├── minimal/
│   │   ├── node/
│   │   ├── python/
│   │   └── go/
│   ├── starter/
│   │   ├── nextjs/
│   │   ├── express/
│   │   └── fastapi/
│   └── production/
│       ├── saas-starter/
│       └── internal-tool/

github.com/your-org/
├── examples/
│   ├── minimal/
│   │   ├── node/
│   │   ├── python/
│   │   └── go/
│   ├── starter/
│   │   ├── nextjs/
│   │   ├── express/
│   │   └── fastapi/
│   └── production/
│       ├── saas-starter/
│       └── internal-tool/

Template Maintenance

模板维护

Real Examples

实际案例

Excellent templates: Supabase

Templates for multiple frameworks
One-click deploy to Vercel/Netlify
Include auth, database, and storage patterns
Actively maintained

Excellent templates: Clerk

Framework-specific quickstarts
Complete with authentication flows
Progressive complexity (minimal → full-featured)

优秀模板案例：Supabase

支持多框架模板
一键部署到Vercel/Netlify
包含鉴权、数据库、存储使用模式
持续活跃维护

优秀模板案例：Clerk

针对不同框架的快速入门
包含完整的鉴权流程
渐进式复杂度（最小示例 → 全功能示例）

Handling Onboarding Failures Gracefully

优雅处理入职失败

Common Failure Points

常见失败点

Installation failures
- Dependency conflicts
- Version mismatches
- Platform-specific issues
Authentication failures
- Invalid API key
- Expired token
- Wrong environment (test vs production)
First request failures
- Network issues
- CORS problems
- Rate limiting
- Invalid request format

安装失败
- 依赖冲突
- 版本不匹配
- 平台特定问题
鉴权失败
- 无效API密钥
- 令牌过期
- 环境错误（测试环境 vs 生产环境）
第一次请求失败
- 网络问题
- CORS问题
- 限流
- 请求格式无效

Error Message Design

错误提示设计

Bad error message:

Error: Request failed with status 401

Good error message:

Authentication failed: Invalid API key

Your API key starts with 'sk_test_' but you're calling the production endpoint.

To fix:
1. Use the production API key (starts with 'sk_live_'), or
2. Change endpoint to https://api.example.com/test/

Docs: https://docs.example.com/auth#environments

糟糕的错误提示：

Error: Request failed with status 401

优秀的错误提示：

鉴权失败：无效API密钥

你使用的API密钥以'sk_test_'开头，但调用的是生产环境端点。

解决方案：
1. 使用生产环境API密钥（以'sk_live_'开头），或者
2. 将端点改为 https://api.example.com/test/

文档：https://docs.example.com/auth#environments

Proactive Failure Prevention

主动故障预防

Detect common mistakes in real-time:

javascript

// Client SDK that catches common errors
if (apiKey.startsWith('sk_test_') && endpoint.includes('/v1/')) {
  console.warn(
    'Warning: Using test API key with production endpoint. ' +
    'This will fail. Use production key or test endpoint.'
  );
}

实时检测常见错误：

javascript

// 客户端SDK捕获常见错误
if (apiKey.startsWith('sk_test_') && endpoint.includes('/v1/')) {
  console.warn(
    '警告：测试环境API密钥用于生产环境端点，请求会失败。请使用生产密钥或切换到测试端点。'
  );
}

Recovery Flows

恢复流程

In-dashboard error recovery:

Something went wrong with your integration.

We detected:
- Last API call: 2 hours ago
- Status: 401 Unauthorized
- Likely cause: API key rotated

[Regenerate API Key] [View Error Logs] [Contact Support]

控制台内错误恢复：

你的集成出现问题。

我们检测到：
- 上次API调用：2小时前
- 状态：401 未授权
- 可能原因：API密钥已轮换

[重新生成API密钥] [查看错误日志] [联系支持]

Measuring Activation Metrics

衡量激活指标

Defining Activation

定义激活

Activation = the moment a developer has enough success to keep using your product.

Different products, different activation definitions:

Product	Activation Definition
Stripe	First successful test charge
Twilio	First SMS sent and delivered
Auth0	First user authenticated
Vercel	First deploy accessible via URL
Algolia	First search returns results

激活 = 开发者获得足够正向反馈，愿意继续使用你的产品的时刻。

不同产品的激活定义不同：

产品	激活定义
Stripe	第一次成功的测试支付
Twilio	第一条短信发送并送达
Auth0	第一个用户完成鉴权
Vercel	第一次部署可通过URL访问
Algolia	第一次搜索返回结果

Core Activation Metrics

核心激活指标

Activation rate

Activated users / Signed up users × 100

Benchmark: 20-40% for self-serve developer products

Time to activation

Median time from signup to activation event

Benchmark: <10 minutes for APIs, <1 hour for infrastructure

Activation by cohort Track weekly or monthly cohorts to identify improvements:

Week 1 cohort: 25% activation
Week 2 cohort: 28% activation (added better error messages)
Week 3 cohort: 35% activation (added interactive tutorial)

激活率

激活用户数 / 注册用户数 × 100

基准值：自助式开发者产品的激活率通常为20-40%

激活耗时

注册到激活事件的中位时间

基准值：API类产品<10分钟，基础设施类产品<1小时

分 cohort 激活率 按周或月 cohort 追踪，识别优化效果：

第1周 cohort：25%激活率
第2周 cohort：28%激活率（优化了错误提示）
第3周 cohort：35%激活率（新增了交互式教程）

Leading Indicators

先导指标

Track behaviors that predict activation:

Leading Indicator	Correlation to Activation
Copied API key	2x more likely
Viewed quickstart	1.5x more likely
Installed SDK	3x more likely
Joined Discord	2.5x more likely

追踪可以预测激活的行为：

先导指标	和激活的相关性
复制了API密钥	激活可能性提升2倍
查看了快速入门	激活可能性提升1.5倍
安装了SDK	激活可能性提升3倍
加入了Discord	激活可能性提升2.5倍

Lagging Indicators

滞后指标

Confirm activation led to value:

Lagging Indicator	Meaning
Day 7 retention	Still using after a week
API calls in week 2	Continued development
Upgrade to paid	Perceived enough value
Invited team member	Expanding usage

验证激活确实带来了价值：

滞后指标	含义
第7日留存	一周后仍在使用
第2周有API调用	持续开发中
升级到付费版	感知到足够价值
邀请团队成员	使用范围扩大

Activation Funnel Example

激活漏斗示例

Signed up: 1,000
├── Visited dashboard: 950 (95%)
├── Viewed quickstart: 700 (74%)
├── Copied API key: 500 (71%)
├── Made first API call: 350 (70%)
├── Got successful response: 300 (86%)  ← Activation
├── Made 10+ API calls: 150 (50%)
└── Day 7 return: 100 (67%)

注册：1000人
├── 访问控制台：950人（95%）
├── 查看快速入门：700人（74%）
├── 复制API密钥：500人（71%）
├── 发起第一次API调用：350人（70%）
├── 获得成功响应：300人（86%） ← 激活
├── 发起10次以上API调用：150人（50%）
└── 第7日回访：100人（67%）

Onboarding Email Sequences

入职邮件序列

Email Timing

邮件发送时机

Email	Timing	Purpose
Welcome	Immediate	Confirm signup, provide key links
Getting started	+1 hour	Drive first API call if not done
Tips	+1 day	Share common patterns
Check-in	+3 days	Ask if stuck, offer help
Activation push	+7 days	Final nudge if not activated

邮件类型	发送时机	目标
欢迎邮件	注册后立即发送	确认注册，提供关键链接
入门指南	注册后1小时	如果用户还没发起第一次API调用，引导操作
使用技巧	注册后1天	分享通用使用模式
跟进邮件	注册后3天	询问是否遇到卡点，提供帮助
激活提醒	注册后7天	未激活用户的最后一次推动

Email Content Principles

邮件内容原则

Do:

Include code snippets (syntax highlighted)
Link to specific docs pages
Offer direct reply for help
Stop sequence once activated

Don't:

Send marketing content during onboarding
Require clicks to view content
Send more than one email per day
Continue sequence after activation

推荐做法：

包含语法高亮的代码片段
直接链接到具体的文档页面
支持直接回复寻求帮助
用户激活后停止发送序列

不推荐做法：

入职阶段发送营销内容
需要点击跳转才能查看内容
每天发送超过1封邮件
用户激活后仍继续发送序列

Examples from Real Developer Tools

真实开发者工具的案例

Excellent Onboarding: Stripe

优秀入职案例：Stripe

Test API keys visible immediately
Interactive "make your first charge" in dashboard
Language-specific code examples
Error messages include fix suggestions
Progress indicator shows completion

测试API密钥注册后立即可见
控制台内交互式「完成第一笔支付」引导
多语言代码示例
错误提示附带修复建议
进度指示器展示完成状态

Excellent Onboarding: Railway

优秀入职案例：Railway

One-click template deploys
No configuration required for common frameworks
Live preview URL in seconds
Clear free tier limits shown

一键模板部署
常用框架无需额外配置
几秒内即可获得预览URL
免费额度限制清晰展示

Excellent Onboarding: Planetscale

优秀入职案例：Planetscale

Interactive database explorer
Import from existing database offered
SQL examples match your schema
Branch workflow explained with visuals

交互式数据库浏览器
提供从现有数据库导入的选项
SQL示例适配你的schema
分支工作流有可视化讲解

Poor Onboarding Patterns to Avoid

需要避免的糟糕入职模式

Multi-step wizards that can't be skipped
"Complete your profile" blocking code access
Documentation requiring search to find quickstart
Quickstarts that assume too much setup
Error messages without guidance

无法跳过的多步向导
「完善个人资料」步骤阻挡代码访问
快速入门需要搜索才能找到
快速入门默认用户已经完成大量前置配置
错误提示没有指导信息

Tools

工具推荐

Onboarding Platforms

入职平台

Appcues - In-app walkthroughs and checklists
Pendo - Product analytics with onboarding features
Userflow - No-code onboarding flows
CommandBar - Developer-focused command palette with onboarding

Appcues - 应用内引导和检查清单
Pendo - 带入职功能的产品分析工具
Userflow - 无代码入职流程搭建工具
CommandBar - 面向开发者的命令面板，带入职功能

Interactive Documentation

交互式文档

CodeSandbox/StackBlitz - Browser-based code environments
Killercoda - Interactive terminal scenarios
ReadMe - API documentation with "Try It" features
Mintlify - Modern docs with embedded code runners

CodeSandbox/StackBlitz - 浏览器端代码环境
Killercoda - 交互式终端场景
ReadMe - 带「试用」功能的API文档工具
Mintlify - 支持嵌入式代码运行的现代文档工具

Email and Lifecycle

邮件和生命周期运营

Customer.io - Behavior-triggered emails
Loops - Email for SaaS
Intercom - Chat + email onboarding

Customer.io - 行为触发邮件工具
Loops - SaaS专用邮件工具
Intercom - 聊天+邮件入职工具

Analytics

分析工具

Amplitude - Onboarding funnel analysis
PostHog - Open source alternative
Heap - Auto-capture for retroactive analysis

Amplitude - 入职漏斗分析
PostHog - 开源替代方案
Heap - 自动采集，支持回溯分析