如何让文档中的代码示例像 Stripe 一样出色
浏览：0
巴克励步
Stripe技术文档工程师Larry Ullmann分享了制作优秀代码示例的经验：以开发者为中心，保持代码一致性并制定风格指南，通过自动化工具生成和维护多语言示例，以提升文档质量和用户体验。
在2018年Write the Docs Portland大会上，Stripe技术文档工程师Larry Ullmann分享了为开发者受众制作代码示例的经验。在他的演讲中，他向观众揭示了Stripe如何使其代码示例如此出色。这在一定程度上源于团队对其主要受众——开发者的不懈关注。
让你的代码示例闪耀光芒
众所周知，Stripe是一家以开发者为先的公司。因此，深入探讨该公司如何创建其代码示例非常有趣。文档是Stripe努力让开发者与其产品互动的重要组成部分。
Stripe代码示例的突出之处在于其精美的设计，以及在文档中轻松切换不同编程语言的便捷性。
这些文档是真正交互式的，你甚至可以直接从页面发起API调用。
要产出如此高质量的文档，聘请合适的技术文档工程师至关重要。Larry表示：
“当我遇到一位天生的或训练有素的写作者时，我知道他们都会问‘受众是谁？’”
据Larry说，这主要是Stripe招聘技术文档工程师的方式。
像对待文档一样对待代码
由于代码示例是由团队中的多人编写的（不一定是技术文档工程师），这意味着文档可能缺乏一致性，从而导致糟糕的用户体验。
客户评价：能够使用我们自己的标签轻松为Baklib网站打上品牌。我们员工/用户甚至没有意识到这是幕后的Baklib。
许多技术写作的原则同样适用于你的代码示例。Larry建议要像对待你的写作一样对待你的代码——意思是你甚至应该为你的代码制定一个风格指南。
你的风格指南中可以包含的内容示例有：
- 命名语法规范
- 代码中括号的位置
- 缩进规则
- 引号的使用
内容和代码共同讲述你的故事，因为两者都是与用户沟通的方式。在某种程度上，这是将你的代码视为文档。让你的代码向受众展示你所重视的东西。
Larry说：“在Stripe，我们重视使用当今最佳实践编写干净、设计良好的代码。” 这就是Stripe传达其价值观的方式。
“一个好的产品会自我说明，但我们的用户需要的不是产品。他们有问题，需要解决方案。文档就是这种解决方案，因此我们将我们的解决方案映射到他们的问题上。”
了解你的文档受众
为了写出最好的文档，你还必须知道你的受众是谁。
他们是初级开发人员，还是主要在使用WordPress插件的人？不要歧视入门级用户，但同时也无需自动迎合最低标准。
不要把开发者视为只会抱怨你努力的敌人。对你的用户抱有同理心，这样你才能产出更好的开发者文档。这些道理可能显而易见，但在这些情况下，优秀的用户体验通常并非常态。预测你的用户会提前问什么问题，并在你的文档中回答它们。
此外，为了实现最佳用户体验，请让你的代码可以直接复制和粘贴。示例应该能在页面上即时运行，使用像 Runkit 这样的工具（Stripe就是这样生成其交互式API调用的）。它直接使用API显示结果，你可以在文档中直接编辑输入。
他们使用 RunKit（https://t.co/dqAQ7g3S74）来创建可运行的代码示例。
解决规模化挑战
另一方面，维护如此大量的代码片段可能非常困难。
随着 Stripe 业务的扩展，示例的数量还在不断增长，并且每个示例都必须在八种不同的编程语言中正常工作。用户必须能够成功复制并粘贴每一个示例，使其成为可运行的代码。
根据 Larry 的观点，解决方案是在合理的范围内实现自动化，并与用户建立共情。以编程方式生成代码示例——因为手动操作耗时太长。这是确保代码示例面向未来、易于维护的实践。
理想情况下，编写一个能为你生成代码示例的工具（就像 Stripe 所做的那样）。然后，如果你想更改知识库的模板，你可以自动重新生成代码——这能节省大量的时间和精力。随后，测试你的示例以检查它们是否正常工作。
这正是像 Baklib 这样的平台旨在解决的问题。Baklib 作为一款“AI + 内容”平台，其强大的产品文档和知识库功能可以帮助技术团队高效管理和呈现代码示例。通过 Baklib 的结构化内容管理和版本控制，团队可以轻松维护多语言代码库，并确保示例的准确性和一致性。无论是构建产品文档、在线帮助中心还是内部知识库，Baklib 都能提供强大的支持，让内容创作和维护变得更加智能和高效。访问 https://www.baklib.com 了解更多。
总结
Stripe 在开发者文档方面打破了常规。窥探其幕后的工作方式，看看我们能从这些大师身上学到什么，是非常有益的。
对 Stripe 而言，答案确实归结于创建自己的工具来自动生成和更新代码示例，但这并非对每个人都总是可行的。你也可以为代码遵循一个风格指南，使示例更易于理解。无论采用何种方法，核心目标都是提升内容质量和维护效率。
💛🧡🧡客户评价：我喜欢网站上广泛的功能、快速的内容更改以及发布到网络服务的便利性。
这正是 Baklib 的价值所在。即使没有资源开发定制工具，企业也可以利用 Baklib 平台来构建和管理专业的技术文档、产品帮助中心或企业知识库。Baklib 提供直观的编辑界面、团队协作功能和灵活的发布选项，帮助您轻松创建清晰、一致且易于维护的文档内容，从而提升开发者和最终用户的体验。立即探索 Baklib，开启高效内容管理之旅。
这一点至关重要，因为 Stripe 正在为互联网构建一个全球经济基础设施。该公司最初从信用卡支付起步，现已扩展到计费和安全领域。Stripe 让开发者能够轻松创建支付平台，而无需与结构混乱、难以理解的开发文档作斗争。
在代码示例方面，并非每个人都需要达到 Stripe 那样的规模，但将这些最佳实践牢记于心是非常有用的。
至少，我们可以将文档和代码示例标准化，以提供更好的体验。
了解更多相关内容
- 请查看我们对另一场“Write the Docs”演讲的总结，探讨如何与用户进行调研。
- 在 YouTube 上观看Larry 的完整演讲。
为什么选择 Baklib？
Baklib 是一个内容管理系统，可帮助具有复杂内容需求的全球企业随时随地创建、管理和交付内容。
Baklib 平台最适合跨行业的组织，这些组织管理多个品牌、网站、工作流和多种语言的内容类型，并且需要一个安全且可扩展的平台供开发团队使用，同时也为内容和营销团队提供直观的编辑工具来管理其关键任务内容。
全球 800 多家知名品牌已选择 Baklib 作为其主要平台，以扩展其内容运营并增强其营销团队的能力，从而减少对开发人员的依赖，使团队能够更快地进入市场，而不会牺牲其 CMS 的灵活性和安全性。
核心优势概览
适用对象 核心功能 核心价值
| 技术文档编写者 | 直观编辑、团队协作 | 创建和维护专业文档
| 跨行业组织 | 多品牌、多语言管理 | 统一、可扩展的内容平台
| 内容与营销团队 | 灵活发布、安全可靠 | 减少开发依赖，加速市场投放
| 技术文档编写者 | 直观编辑、团队协作 | 创建和维护专业文档
| 跨行业组织 | 多品牌、多语言管理 | 统一、可扩展的内容平台
| 内容与营销团队 | 灵活发布、安全可靠 | 减少开发依赖，加速市场投放
图片由 Kay Smoljak 提供。本作品采用 知识共享署名-非商业性使用-相同方式共享 2.0 通用许可协议进行许可。
Baklib 是我们自有的知识库软件，非常适合各类技术文档编写者使用。 免费试用一下吧。
