API 文档是参考资料;开发者演示则是入门指南。您的文档列出了每个端点、参数和响应代码,但开发者首先需要的是理解其概念:API 的功能、身份验证机制以及如何进行首次调用。借助 Gamma,您可以连接文档源或粘贴内容,让 AI 代理在几分钟内将繁杂的参考资料转化为清晰、可视化的开发者演示,其中包含概念、流程和示例调用。
挑战在于顺序。文档的组织方式是为了方便查找、按字母顺序排列端点、列出详尽的参数,而演示文稿则必须以循序渐进的方式进行讲解。你不可能通过从上到下阅读参考文档来引导开发人员入门。Gamma 的代理会阅读你的文档,询问集成人员是谁以及他们需要完成什么,然后将内容重新组织成一个能够帮助开发人员成功完成首次调用的演示文稿。
优秀的开发者演示能将参考文档转化为易于理解的内容:
首先解释 API 的功能以及它解决的问题
提前完成身份验证,因为没有它一切都无法运行。
在介绍端点之前,先展示核心概念和资源模型。
演示首次通话流程,包括具体的请求和回复。
突出显示开发人员实际会使用最多的关键端点
指向完整文档,了解其他所有内容
最好的开发者演示能让观众产生“我明白如何使用这个”的感受,而不是“我已经看过每一个接口”。
连接文档所在的工具,例如 Confluence、GitHub 文档仓库或 Notion,Gamma 即可直接导入内容,无需复制粘贴。更喜欢直接在文件中操作?只需粘贴参考文档或 Markdown 代码即可。无论哪种方式,Gamma 都能读取并理解其 API 文档。连接数据源只需不到一分钟,即使 API 发生变更,也能快速更新演示文稿。
Gamma 的代理会确认集成者的身份和目标,阅读文档,并将其整理成一个流程,其中包含:概述、身份验证、概念、首次调用、关键接口和资源。参考资料最终会形成一个帮助用户逐步理解的叙述。
Gamma 会自动将您的示例请求转换为易读的代码块,将您的身份验证和请求流程转换为图表,并将您的资源模型转换为清晰的可视化图像。开发人员无需面对冗长的参考文本,即可轻松理解概念。
连接您的文档源或准备好要粘贴的参考内容。概览、身份验证和一些关键端点为代理提供了最全面的功能。
打开 gamma.app,从提示框开始。连接你的文档或粘贴内容,然后提出你的需求,例如:“将此 API 文档转换为面向集成我们 API 的工程师的开发者入门演示文稿,内容涵盖身份验证、核心概念和首次调用。” 向代理提供一两个简短的答案,它就会开始工作。
Gamma提出了一个概要。典型的开发者演示流程如下:
API 的功能以及何时使用
身份验证和获取凭据
核心概念和资源模型
您的首次请求和回复
关键端点和常用工作流程
错误、限制和最佳实践
完整文档和资源
根据受众群体重新排序、添加或删除章节。需要先获取授权信息的合作伙伴?那就把这部分内容提前。
Gamma 可生成完整且格式规范的开发者演示文稿,其中包含您的代码块、流程图,并确保整体风格一致。对于合作伙伴或产品发布简报,Max 模式则使用功能最强大的模型,进一步提升演示文稿的精美度。
布局已预先构建,因此每个概念都能精准呈现。如果您需要精确放置代码块或图表,请切换到自由编辑模式并进行精确定位。想要描述更改内容?使用 AI 编辑功能,选择任意元素并告诉 Gamma 执行什么操作,例如“以图表形式显示授权流程”或“突出显示必需参数”。将每个标题精简到核心要点。
您可以进行实时演示,分享可供开发者随时访问的交互式网页链接,或导出为 PowerPoint、PDF 或 Google Slides 格式。您的代码、图表和格式都将保留,因此开发者可以获取他们喜欢的任何格式的资料。
Gamma 与直接引用文档的对比
格式:文档的组织方式便于查找;演示文稿需要有条理的讲解顺序。
节奏:参考资料堆积如山;Gamma 则能精准地找出开发者最需要的内容。
视觉效果:文档以文字为主;Gamma 将流程和概念转化为图表。
实话实说: 请将 API 文档作为完整的参考资料,这正是它们的用途。在进行开发者入职培训时,让 Gamma 将文档转化为教学演示文稿,并引导用户参考完整的参考资料以获取详细信息。
Gamma 与 PowerPoint 的比较
来源:PowerPoint 初始状态为空白;Gamma 直接读取您的文档或连接的源文件。
更新:当 API 发生更改时,PowerPoint 需要手动操作;而在 Gamma 中,您可以快速从源文件重新生成。
设计:PowerPoint 的质量取决于您;Gamma 值保持一致。
实话实说: PowerPoint 让您可以完全掌控定制化的简报。而 Gamma 可以更快地将文档转换为入职培训演示文稿,并且您可以随时导出回 PowerPoint。
以思维模型为先导。 开发人员需要先了解 API 的结构,然后再了解端点。
尽早完成身份验证。 在用户完成身份验证之前,其他一切都无法运行,所以不要把它藏得太深。
展示一个真实的首次调用。具体的请求和响应比参数表更能说明问题。
不要列出所有接口。重点突出开发者最常用的几个接口,并提供其他接口的链接。
保留完整的参考资料。 引导读者查阅文档以获取详尽的细节,而不是将其塞进正文。
是的。连接 Confluence、GitHub 文档仓库、Notion 或任何你存放文档的地方,Gamma 就会直接导入内容。你也可以根据需要粘贴参考资料。
是的。Gamma 会将代码渲染成清晰易读的代码块。请保持示例简洁明了,并使用 AI 编辑功能突出显示所需的参数或关键行。
Gamma 可以将您描述的流程图转换为清晰的图表。您可以自由编辑以完善它们,或者让代理简化流程。
如果您的文档源已连接,请让 Gamma 刷新以显示更新后的内容,或将其另存为模板。文档结构保持不变,只有内容会更新。
您的文档已经描述了所有接口,但它仅用于查找,而非引导用户上手。请关联您的文档或粘贴内容,告诉 Gamma 您的目标受众及其目标,然后让代理将参考资料转换为包含代码和图表的教学演示文稿。这样,您就能帮助开发人员快速完成首次成功通话。
