飞书开放平台：新手引导体系设计

项目一句话

我在飞书开放平台的新手引导项目中，负责把“开发者不知道从哪里开始”的模糊问题，拆解成不同用户类型、不同阶段、不同入口下的路径设计，并推进文档目录、开发引导、官网入口和内容资产的系统化改造。 这不是一个单纯的页面改版项目。它要解决的是：开放平台能力很多、文档很多、入口很多，但新用户缺少一条能从“理解平台能做什么”走到“完成第一个有效应用”的路径。

为什么要做

开放平台面对的不是单一用户，而是几类目标完全不同的人：

• 自建应用开发者：希望快速判断开放平台能否解决企业内部业务问题，并完成第一个应用。
• SI 服务实施伙伴：需要清楚知道平台能力目录、最佳实践和开放平台/集成平台的边界，才能服务客户。
• ISV 开发者：关注入驻、方案评审、上线自检、审核发布等流程成本。 在项目早期，问题看起来像是“文档太多、不好找、示例不足”。但我进一步判断，真正的问题不是某一篇文档不好，而是用户没有路径感：
• 不知道自己应该先看案例、看能力，还是直接开始开发。
• 不知道开放平台的能力和自己的业务场景怎么对应。
• 不知道完成第一个应用需要经过哪些步骤。
• 遇到权限、调试、错误码、发布问题时，不知道去哪里找确定答案。 所以这个项目的核心目标，不是再补几篇文档，而是重建一个从认知到行动的 onboarding 体系。

我的角色

我主要负责和参与 4 件事：

1. 拆解开放平台新手用户路径，明确不同类型用户在不同阶段的核心任务。
2. 推进文档目录分层级，让复杂文档体系更符合新手学习和任务查找路径。
3. 推进开发引导方案，串联平台介绍、能力介绍、开发教程和后台内的行动入口。
4. 推进官网优化和内容资产显性化，把内部沉淀的案例、方案、视频、最佳实践变成用户可发现的入口。

我具体做了什么

1. 重新定义问题：从“文档体验”转向“路径体验”

我没有把问题停留在“文档不好找”这一层，而是把用户的上手过程拆成三个连续阶段：

• 调研能力：用户还没有决定要开发什么，核心问题是“飞书开放平台能帮我解决什么”。
• 开发应用：用户已经有目标，核心问题是“我怎样从添加能力走到完成开发”。
• 上架发布：用户接近上线，核心问题是“我怎样低成本完成审核、权限、测试和发布”。 这个拆解来自调研数据：Q3 满意度调研中，调研开放能力的用户占 57.42%，开发应用占 53.23%，上架商店应用占 14.52%。这说明很多用户并不是一进来就准备写代码，而是先在判断平台能力和业务场景是否匹配。 因此，我把方案主线从“把用户导向开发文档”调整为“了解案例 -> 调研能力 -> 开始开发 -> 发布上线”。这条路径更贴近真实决策过程。

2. 推进满意度调研和机会点沉淀

在满意度调研阶段，我参与了一个关键判断：只调研新增开发者样本量可能不足，所以应该覆盖所有开发者，包括曾经的新手用户，用更大的样本回看 onboarding 问题。 调研和访谈后，我把用户问题转译成可设计的机会点：

• 学习探索阶段：用户需要清晰学习路径、直观入门引导、示例代码和可回溯内容。
• 正式开发阶段：用户需要权限解释、错误码解决方案、调试记录、智能助手和社区支持。
• 发布上线阶段：用户需要更低摩擦的测试租户、权限审批和发布流程。 这里我的重点不是整理痛点列表，而是判断每类问题应该由什么承载：信息架构、教程、案例、官网入口、后台引导，还是 AI/人工支持体系。

3. 负责文档目录分层级

开放平台文档承载了大量能力说明，但对新用户来说，平铺的能力目录会放大认知负担。 我推进文档目录分层级，目标不是把目录做得更复杂，而是让用户更快判断：

• 我现在处在哪个学习阶段。
• 我应该先理解概念，还是直接进入能力教程。
• 如果我遇到权限、错误码、调试、发布问题，该去哪一层找答案。 我的设计判断是，文档不能只按内部能力组织，也要按用户任务和学习阶段组织。新手需要看到基础概念、快速开始和典型场景；有明确目标的开发者需要直接进入能力教程；遇到问题的开发者需要能快速定位支持内容。 这件事表面是目录优化，本质是重建开发者的学习地图。

4. 推进官网优化和内容资产显性化

服务实施团队和内部团队已经沉淀了很多集成案例，比如 SSO、组织架构迁移、审批集成等。但如果这些案例只停留在内部，就仍然需要 CSM、TC 或服务团队反复人工解释。 我参与推进官网优化，把案例、解决方案视频、开放能力展示、ISV/自建应用入口等内容前置。这里的思考是：官网不只是品牌展示页，也应该承担 onboarding 的第一段职责。 用户在官网阶段就应该能完成三件事：

• 看懂开放平台能解决什么问题。
• 找到和自己业务相似的案例或方案。
• 知道下一步应该调研能力、进入教程，还是联系服务支持。

结果

这个项目的结果我会分成“已经明确产生的结果”和“仍需数据验证的结果”两类看。 已经明确产生的结果：

• 团队对 onboarding 问题的理解从“文档不好找”升级为“用户路径不连续”。
• 明确了开放平台新手用户的三条主路径：调研能力、开发应用、上架商店应用。
• 形成了文档目录、开发引导、官网入口、案例资产、AI 支持等多条相对独立但能互相衔接的方案线。
• 设计方案完成初步验证，并进入开发与灰度跟进阶段。

我的思考

1. 新手引导不是教用户点哪里，而是帮用户做判断

对开放平台这种复杂产品来说，新手引导不是简单告诉用户“下一步点击哪里”。真正困难的是帮助用户判断：我是谁、我要解决什么问题、平台里哪条路径适合我。 所以我更关注判断框架，而不是单点交互。

2. 内容体系本身就是开发者产品体验

在开发者产品里，文档、案例、教程、错误码、权限解释都不是产品之外的帮助材料。它们就是产品体验的一部分。 用户能否完成第一次成功开发，很大程度取决于内容是否在正确时机、以正确结构出现。因此内容体系不能在最后补，它应该和产品结构一起设计。

3. 不同开发者不能共用一条 onboarding

自建应用开发者、SI 伙伴、ISV 开发者都叫“开发者”，但他们要完成的任务完全不同。

• 自建应用开发者要快速解决企业内部业务问题。
• SI 伙伴要理解能力目录和最佳实践，判断能为客户交付什么。
• ISV 开发者要完成入驻、审核、发布和商业化流程。 如果用同一条路径服务所有人，体验一定会变得模糊。好的 onboarding 应该尽早识别用户意图，并把用户带到更贴近目标的路径里。