关于开发者体验（译）

以下是我认为创造良好开发者体验（DX）的因素：

框架和库

• 让入职变得快速：你应该能够用一个命令尝试一个新工具。例如，npx create-next-app或者brew install bat然后，它应该能够快速迭代并看到工具的价值，并向开发者提供快速反馈。
• 使升级变得简单：当进行主要版本变更时，应限制变更的“爆炸半径”，以便于人们更新依赖项。理想情况下，变更应该最初是可选的，并在主要版本发布前有好几个月的提前时间。然后，主要版本应该包括codemods——运行代码转换的脚本，以帮助自动迁移代码并修复破坏性变更。
• 有用的错误信息：在适用的情况下，在错误信息中包含超链接，以便提供更多关于如何解决错误的上下文。你的工具应该在你输入时提供反馈。越快越好（例如，类型检查，linting）在运行时或编译时错误之前。不要让我思考.
• 强大的默认设置和惯例：对构建软件的“正确方式”持有意见。例如，不要让我考虑设置路由，只需使用Next.js的基于文件系统的路由。不要让我配置编译和打包，只需为我设置webpack/swc/vite/esbuild的良好默认值。
• 提供紧急出口：对抗强默认设置的方法是确保开发者想要打破标准配置时有逃生舱口。Next.js在最初成功的原因之一是能够轻松覆盖webpack_没有_离开框架，而CRA需要类似的东西克拉科弹出后。
• 降低依赖风险：当你npm i next，你只需要从npm安装13个依赖项。其余的依赖项都内嵌到Next.js中，以加快安装时间并提高安全性。将来，我们希望将Next.js变成一个单一二进制你可以安装。

文档

• 用代码领导：开发者想要编写代码。给他们代码示例作为起点。不要掩盖主题。
• 使找到答案变得简单：开发者来到文档是为了找到他们试图解决的问题、挑战或疑问的答案。通过多种方式（视频、文本、教程、指南等）给他们答案。提供一个AI驱动的搜索，该搜索索引了你的文档内容的全部。
• 自动化文档编制：在记录API时，从真相的源头（代码）生成文档是有帮助的，以确保它们保持同步。例如，Vercel的API文档就是从其开放API规范.
• 不仅仅是快乐的道路：该文档是一份供开发者参考的指南，他们试图完成工作。通常，这意味着搜索一个错误并寻找一个他们可以复制/粘贴的解决方案。同样重要的是记录变通方法和黑客行为。我宁愿承认产品中存在差距，并且_解封_开发者不应该让他们感到沮丧。
• 优化以便于浏览：我们都略读，尤其是当阅读密集的技术文档时。我的眼睛会直接跳到代码块，试图找到我给定问题的解决方案。考虑在代码片段中添加有用的代码注释，并展示多个选项或期望的特性/ API的排列组合。
• 请准确：避免使用术语和成语。如果你使用了一个缩写词，第一次时请拼写出来，不要假设读者知道它是什么。你的文档应该对初学者和专家都是可访问的。考虑将对专家有帮助但对快乐路径不关键的内容放在可折叠的深入研究部分。
• 逐步展现复杂性：在用户初次使用时保持简单，随着他们继续构建，逐步展示更复杂的功能。我们不能指望开发者一开始就了解整个平台的全部内容。

应用程序编程接口

• 不要破坏API工作流：API版本控制应该是有意的和明确的。在对API进行更改时，要倾向于过度沟通，并给开发人员足够的时间来更新到新版本。我个人很喜欢Stripe的API版本控制——他们有一篇极好的文章如果你想学习更多。我已经看到一些实例，AWS发送了一个关于一个已经稳定运行多年的API的弃用电子邮件，并且给了他们多年的升级时间。
• 让我快速尝试API：我最喜欢的一些API文档允许你在几秒钟内生成一个API密钥并尝试端点。有些甚至能识别你已经登录，并根据你的账户信息个性化页面。正方形做得很好。 我还喜欢GraphiQL，你可以查看整个图形模式，提出请求，运行突变，格式化代码等等。

原文链接：On Developer Experience

本文使用 🐝 A C(Collect) -> T(Transform) -> P(Publish) automation workflow for content creator. 全自动采集 - 翻译 - 发布