他山之石：什么造就了卓越的开发者体验？

本期他山之石的内容来自 Lee Robinson 的 What Make a Great Developer Experience?. Lee Robinson 是 Vercel 的产品 VP，同时自己也是一个前端开发者，协助 Next.js 构建社区。

以下是我对什么构成优秀的开发者体验（DX）的一些看法的集合。请注意，其中一些观点比它们的类别更广泛适用（例如，框架）。

框架与库

• 尽可能快的 Onborad ：为了让创意保持在心流中，你席位他们可以尽可能快的开始。尽力确保框架和库面向「快速开始」优化。例如 npx create-next-app 或 brew install bat。面向快速优化迭代，并尽可能快的将反馈给予开发者。
• 简化升级过程：在执行主要版本（Major Vercion）变更时，限制变更的「影响范围」，以帮助人们轻松的更新依赖项。理想情况下，变更应该从可选进入（Opt-in）开始，并在正式纳入主要版本之前有数月的时间进行提前通知。然后主要版本变更应该包含 codemods — 一个可以通过运行代码转换脚本来帮助自动迁移代码，并修复破坏性变更的部分。
• 有用的错误信息：如果可以的话，在错误信息当中包含超链接，以提供更多关于如何解决错误的上下文。你的工具应该在输入时提供反馈。在运行时或编译报错之前，越快越好（例如类型检查、代码风格检查）。Don't Make Me Think。

• 强大的默认值和约束：要对于「正确构建软件的方式」有观点。例如，不要考虑让我去设置路由，只使用 Next.js 的基于文件系统的路由。不要让我去配置编译和打包，只需使用 webpack/swc/vite/esbuild 并为我配置好的默认值。
• 提供逃生路径：对抗强默认值的方法是确保开发者想要从标准配置跳出时，有逃生路径。Next.js 最初之所以成功，就是能够轻松地在不离开框架的情况下覆盖 webpack 的配置，而 CRA（Create React App） 在 eject 之后则需要类似 craco 的东西来实现相同的效果。
• 降低依赖风险：当你执行 npm i next 时，你只需要从 NPM 安装 13 个依赖项。其余的依赖项目早已内联到 Next.js 之中，以实现更快的安装时间和提高安全性。未来，我们希望将 Next.js 转换为一个可安装的单个二进制文件。

文档

• 以代码为起点：开发者们想要编写代码，给他们代码示例作为起点，不要埋没重点。
• 解决问题（aka：回答问题）：开发者来到文档中学习他们试图解决的疑问、挑战或问题的答案。通过多种方式（视频、文本、教程、指南）提供答案，让他们以适合自己的方式学习解决方案。
• 自动化文档：当为 API 撰写文档时，从真相的来源（代码）中生成文档有助于确保他们保持同步。例如，Vercel 的 API 文档是从 其 OpenAPI 规范中自动生成的。
• 不是只有快乐路径：文档是开发者完成工作的参考指南。通常情况下，这意味着寻找错误并寻找可以复制粘贴的解决方案。记录小技巧和解决方案也同样重要。我宁可承认产品中的差距，并解决开发者的问题，也不愿意让他们因为无法完成工作而感到沮丧。
• 优化快速浏览：让我们面对现实，我们都会快速浏览。在阅读开发者文档时尤甚。我的眼睛会直接跳转到代码块，试图找到解决我的问题的方案。为了帮助提供最好的 DX，请认真考虑在代码片段当中添加有用的代码注释，并展示多个所需功能/API 的选项或排列组合。
• 精确：避免使用技术术语和俚语。如果你使用缩写，第一次出现时请拼写出来，不要假设读者知道它的意思。你的文档应该对于初学者和专家都同样易于理解。考虑将有助于专家但非快乐路径关键内容放在可折叠的「深入探讨」部分。
• 逐步暴露复杂度：在保持首次体验清晰的同时，逐步向开发者介绍更复杂的功能，以便于他们在继续使用产品时了解。预期开发者了解整个平台来开始使用是不切实际的。

APIs

• 不要破坏 API 工作流程：API 应当设计意图明确的版本化。在修改 API 时，应倾向于充分沟通，并给开发者充足的时间更新到新版本。我个人很喜欢 Stripe 的 API 版本化。如果你想要了解更多，他们有一篇很棒的文章。我见过一些情况，AWS 会发送一个已经稳定多年的 API 的弃用邮件，并且给他们提供了多年的升级时间。
• 让我快速尝试 API：我喜欢某些 API 文档允许你在几秒钟内生成 API 密钥，并尝试调用。一些网站甚至能够识别到你已经登录，并根据你的账户信息对页面进行个性化调整。 Square 在这方面做的很好。我也很喜欢 GraphiQL，你可以查看整个的图 Schema、发起请求、执行修改（Mutation）、格式化代码等等。

相关阅读

• 开发者体验的案例
• 什么是体验工程（Experience Engineering）？
• 开发者体验雷达图
• 什么是开发者体验？来自 Adam Wathan（Tailwind CSS） & Lee Robinson （Vercel）