developer-onboarding

Name: developer-onboarding
Author: jonathimer

github.com/jonathimer营销与增长87102 次安装35 周前更新

代码仓库

关于 developer-onboarding

面向产品与开发者营销团队的入门引导技能，帮助开发者更快获得有用成果，涵盖快速入门、故障恢复与激活度量。

主要功能

01优化首次价值耗时
02设计快速入门清单
03选择交互式或静态教程
04规划示例应用与模板
05改进错误恢复流程
06衡量激活漏斗

适用场景

01审查注册到首次成果的阻碍
02编写以任务为核心的快速入门
03检查入门错误及恢复方式
04按用户群组追踪激活情况

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jonathimer/devmarketing-skills --skill developer-onboarding

安装后在 Claude Code 中输入/developer-onboarding确认已加载。

附带文件README.md

详细介绍

开发者引导

尽可能快地让开发者从注册到编写可运行的代码，然后引导他们进一步深入使用。

概览

开发者引导是从“我注册了”到“我知道怎么使用它”之间的关键阶段。你大约有 10 分钟的时间吸引开发者的注意力。每一秒的困惑、每一条没有指导信息的错误消息、每一次“应该能用但就是不行”的体验，都会让你失去用户。

出色的引导就像有人预判了你的所有问题，陪你一起编程。糟糕的引导则像把你丢在一座没有地图的陌生城市里。

开始之前

查看 /devmarketing-skills/skills/developer-audience-context 技能，了解你的目标开发者。构建副项目的爱好者与评估生产环境工具的企业架构师，需要不同的引导方式。查看 /devmarketing-skills/skills/developer-signup-flow，确保注册流程能顺畅衔接引导流程。

优化首次价值实现时间

定义“首次价值”

首次价值不只是“发起了一次 API 调用”。首次价值是开发者看到你的工具为他们完成了有用的事情。

工具类型	首次价值时刻
API	返回有意义数据
SDK	库执行预期功能
数据库	查询返回结果
托管服务	应用上线并可访问
身份验证	用户成功登录
支付	测试扣款成功处理

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

记录每个阶段的时间戳：

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 分钟

消除 TTFV 障碍

梳理每个步骤并消除阻碍：

常见的 TTFV 杀手：

访问控制台前必须验证电子邮件
API 密钥藏在账户设置中
快速入门教程假定依赖项已安装
首个示例需要付费功能
错误消息没有提供解决指导
文档搜索结果包含过时教程

TTFV 审核流程：

创建新账户（使用全新的浏览器，不带 Cookie）
录下最初 30 分钟的屏幕操作
记录每次困惑或受阻的时刻
记录每个步骤所用的时间
使用 5 种不同的开发者角色重复测试

快速入门清单设计

理想的快速入门结构

# Quickstart: [Specific Goal] in 5 Minutes

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

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

## Step 1: Install the SDK
[One command, copy button]

## Step 2: Initialize with your API key
[Code with placeholder, copy button]

## Step 3: Make your first request
[Complete working example, copy button]

## Step 4: See the result
[Expected output shown]

## Next steps
- [Link to common second task]
- [Link to full documentation]

行之有效的清单模式

进度指示器（Stripe 风格）：

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

情境化后续步骤（Vercel 风格）：

You've deployed your first site.

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

常见的快速入门失败案例

一开始就提供过多背景信息：

# Bad: The history of authentication
Before we begin, let's understand OAuth 2.0...
[500 words of background]

# Good: Jump to action
Install the SDK and make your first authenticated request.

假定用户的环境：

# Bad
Run `npm install` to install dependencies.

# Good
npm install our-sdk
# Or with yarn: yarn add our-sdk
# Or with pnpm: pnpm add our-sdk

隐藏的先决条件：

# Bad (prerequisite discovered in Step 3)
Step 3: Connect to Redis
First, make sure Redis is running...

# Good (prerequisites listed upfront)
Prerequisites:
- Redis 6+ running locally (docker run -p 6379:6379 redis)

交互式教程与静态教程

何时使用交互式教程

交互式教程适用于：

复杂的设置流程
能从即时反馈中受益的概念
由你控制环境的引导流程
需要 API 密钥或凭据的功能

交互式教程工具：

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

何时静态文档更合适

静态文档更适用于：

参考文档
可复制粘贴的代码片段
涉及本地开发的步骤
经常变更的内容

混合方式

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

# Make Your First API Request

## Quick version (copy-paste)
[Code block with copy button]

## Interactive version
[Launch in StackBlitz] [Try in CodeSandbox]

## Video walkthrough
[5-minute embedded video]

交互式教程的用户体验指南

应该：

自动保存进度
允许跳到后续步骤
显示预计剩余时间
提供跳转到静态文档的途径
支持移动浏览器（至少能够查看）

不应该：

要求用户创建账户才能使用教程
自动播放视频
将内容锁定在已完成的步骤之后
不发出警告就让空闲会话超时
要求使用特定的 IDE 或浏览器

示例应用和模板

模板策略

分层方法：

最小示例（Hello World）
- 单个文件
- 除 SDK 外零依赖
- 30 秒内即可运行
- 目的：验证 SDK 是否可用
入门模板（基础应用）
- 简单的文件夹结构
- 展示常见模式
- 5 分钟内即可运行
- 目的：为实际项目提供起点
生产级模板（完整应用）
- 可用于生产的架构
- 包含身份验证、错误处理和测试
- 30 分钟内即可运行
- 目的：提供参考实现

模板组织

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

模板维护

无法正常运行的模板比没有模板更糟。

模板健康检查清单：

每周对所有模板运行 CI
每月更新依赖项
固定 SDK 版本，并随发布更新
每季度让新贡献者测试 README
在移除模板前添加弃用通知

实际示例

优秀模板：Supabase

提供多个框架的模板
支持一键部署到 Vercel/Netlify
包含身份验证、数据库和存储模式
积极维护

优秀模板：Clerk

针对特定框架的快速入门
包含完整的身份验证流程
复杂度逐步递增（最小 → 功能完整）

优雅地处理入门失败

常见失败点

安装失败
- 依赖冲突
- 版本不匹配
- 特定平台的问题
身份验证失败
- API 密钥无效
- 令牌已过期
- 环境错误（测试环境与生产环境）
首次请求失败
- 网络问题
- CORS 问题
- 速率限制
- 请求格式无效

错误消息设计

糟糕的错误消息：

Error: Request failed with status 401

良好的错误消息：

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

主动预防失败

实时检测常见错误：

// 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.'
  );
}

恢复流程

在控制面板中恢复错误：

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]

衡量激活指标

定义激活

激活 = 开发者取得足够的成功，从而愿意继续使用产品的时刻。

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

产品	激活定义
Stripe	首次成功测试扣款
Twilio	首条短信发送并送达
Auth0	首位用户完成身份验证
Vercel	首次可通过 URL 访问的部署
Algolia	首次搜索返回结果

核心激活指标

激活率

Activated users / Signed up users × 100

基准：自助式开发者产品为 20-40%

激活时间

Median time from signup to activation event

基准：API 少于 10 分钟，基础设施少于 1 小时

按群组划分的激活 跟踪每周或每月的用户群组，以发现改进之处：

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

领先指标

跟踪能够预测激活的行为：

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

滞后指标

确认激活是否带来了价值：

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

激活漏斗示例

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%)

入门邮件序列

邮件发送时间

邮件	时间	目的
欢迎邮件	立即	确认注册，提供关键链接
开始使用	+1 小时	若尚未完成，则推动首次 API 调用
使用技巧	+1 天	分享常见模式
跟进	+3 天	询问是否遇到困难并提供帮助
推动激活	+7 天	若尚未激活，则进行最后提醒

邮件内容原则