数字技术战略：开发者体验 —— 内部工具的“最后一公里”

Posted 2021-09-15 phodal

这是一篇迟来的文章，我本应该在很早之前写完，但是一直都发现时机不够成熟。去年，在经历了多个低代码前端项目的售前，以及一个低代码项目的技术实践强化，国内的 IT 企业缺乏对于『开发者体验』缺乏系统性的思考。

来，先我们来看一个开发者体验（DX，Developer Experience）的定义：

开发者体验，与用户体验类似，只是对象是软件开发人员。将之与国际进行对应，便是开发人员对于针对使用或期望使用的产品、系统或者服务的认知印象和回应。有所不同的是，用户关注的内容变为库，SDK，文档，框架，开源解决方案，通用工具，API 等的开发人员的体验。

而完善开发者体验是有一些基础条件的：

• 稳定性。SDK、库、框架等具备满足使用方持续可用的状态。
• 功能完备。可以满足大部分的正常的功能需求。

简单来说，就是只有在可用的情况下，设计开发者体验会更加有价值，即开发者体验是一个加分项。而如果我们能在开发的前期就考虑用户体验的话，它会为后续的开发带来便利。

开发者在体验什么？

什么是开发者体验？那不就是让开发人员觉得爽吗。

什么才叫爽呢？来一起看几个例子。

安装谁更简单？

先让我们来看一个软件安装的例子：

1. 一键命令行安装。如 curl --proto \'=https\' --tlsv1.2 -sSf https://sh.rustup.rs | sh
2. 按步就班下载和使用。如打开官网，找到对应的平台（操作系统）下载可执行文件，打开安装软件，执行安装步骤，一步步进行。

这是 Rust 官方提供的两种不同的 Rust 安装方式。

谁的引入更简单？

再看个使用软件的例子：

1. README 即起步文档，添加依赖，复制示例代码。
2. README 里没有起步，需要跳转到文档网站，添加依赖，添加构建脚本，复制示例代码。

两者都是 Rust 里的语法解析器，前者是拥有 2.2k stars 的 pest，后者则是拥有 1.7k stars 的 lalrpop。

这里，先不讨论两个不同的库在开发上的区别，从直观感受来说，我们就可以直接区别。

起步谁更快？

来两看两个上手指南

1. 学习新的语言，学习新的语法，入门文档很长（start），还需要编译，文档不易访问。
2. 通过 script 标签引入 ，直接开始编写代码。

你觉得新手会选择 Vue 还是 Angular？

开发者体验

这样一来，我们对于开发者体验都能有一个简单的体会。也就能理解什么是开发者体验了。

什么是开发者体验？

开发者体验是指开发人员在使用软件、工具、代码等的体验，它与用户体验类似，只是对象是软件开发人员。将之与国际进行对应，便是开发人员对于针对使用或期望使用的产品、系统或者服务的认知印象和回应。有所不同的是，用户关注的内容变为库，SDK，文档，框架，开源解决方案，通用工具，API 等的开发人员的体验。

国内开始关注开发者体验主要有以下的一些原因：

• 外部开源。即越来越多的开发人员开源了自己的软件，迫切地需要提升软件的体验。
• 内部开源。在内部通过开源来进行部门之间的协同效应。
• 内部基础设施共享。让内部的开发人员使用内部的基础设施时，获得比外部开源软件更好的体验，提升其在内部的口碑。
• API 经济。对外提供 API，需要与更多的业内组织竞争。
• 云原生。云厂商面向开发者提供服务。
• 生态构建。面向合作伙伴需要提供更便捷的接入服务。
• SDK 等工具提供方。
• ……

原因多种多样，但是其核心都是想通过开发者体验来提升竞争力。

开发者体验六要素

再次强调一下：关注开发者体验之前，应该确保核心功能：完善 + 稳定。即你需要提供可用、稳定的特性，再去提升总体的用户体验。除非，对于你的系统来说，你在一开始就不缺用户。

从我在开发社区的使用经验、网上了解的相关信息以及与一些专业人士的沟通中，我认为以下几点是进行 DX 时要考虑的要素：

• 错误呈现。即出错时，以何种方式来呈现。
• 文档体验。
• 易用性。如何简化开发。
• 交互式。降开发者学习成本。
• 触点。让更多的人知道这个软件。
• 支持。

太长不看版：

错误呈现	文档体验	易用性	交互式	触点	支持
错误描述	开发者门户	一键式安装	低配置/零配置	文章	问题反馈渠道
报错即文档	发布日志	自动化版本迁移工具	声明式使用	演讲/分享	问题响应时间
报错即修改建议	代码生成文档	自助式搭建	可交互文档	Hackathon	开发者即服务
	版本迁移指南		沙盒及产品环境		开发者社区

可能还有其它内容，如果有的话，欢迎与我探讨。

错误呈现

PS：出于安全原因，有些内容不适合在外部暴露，因此并不建议所有的东西都应该对外呈现。

对于开发者体验来说，错误呈现就是让开发者有办法快速定位问题和修改问题。常见的一些可优化的部分是：

• 错误描述。即软件的出错以合理的方式描述出来，可能是一段文字，一个错误码等。
• 报错即网站。即复杂的出错场景里，可以通过可访问的链接来告诉开发者如何修改问题。
• 报错即修改建议。即出错时，告诉开发人员可以尝试以下的方式来修改问题。

这里，我们可以看一个 Rust 出错的示例：

error[E0425]: cannot find value `RE_ACCESS` in this scope
...
177 |           if let Some(capts) = RE_ACCESS.captures(line) {
    |                                ^^^^^^^^^ help: a static with a similar name exists: `RE_CLASS`

虽然，这个提醒不一定那么智能。但是，它在帮助定位问题的同时，还在一定程度上来解决一点问题。

文档体验

文档是一种传统知识的载体。优秀的程序员即能通过代码来传递知识，还会通过文档来表达自己。

软件编程即理论建立与传递。 —— Peter Naur

对于文档来说，依旧的，我们还会关注于：

• 开发者门户。作为整个知识体系的承载
• 发布日志/更新日志。即 CHANGELOG.md
• 代码生成文档。
• 版本迁移指南。针对于出现 Breaking Change 的场景，需要详细给出每一部分的迁移示例。
• 测试用例。在开源世界里，除了文档，还有测试用例可以读懂一些特别的用法。

开发者门户是一个复杂的话题，后面我们会再介绍。如下是 D3.js 6.0 的 migration guide 示例：

For example,

  selection.on("mousemove", function(d) {
    … do something with d3.event and d…
  })

becomes:

  selection.on("mousemove", function(event, d) {
    … do something with event and d …
  })

我们还会在易用性里提供更好的方式。

易用性

易用性本身是非常难度量的，

• 一键式安装。可以是一行命令，也可以是 1-click 之类的。
• 自动化版本迁移工具。即针对于版本升级时的 API 修改，可以提供自动修改工具，典型的如 Angular CLI 来升级 Angular。
• 自助式搭建。如 Spring Initializr，可以让开发人员选择合适的服务和工具，而后生成项目等。

在高中时期，我尝试了市面上的一个又一个 GNU/Linux 改行版。如 Ubuntu 和 OpenSuSE 会向我们寄一些安装 CD/DVD，用来帮助新手快速安装 GNU/Linux 操作系统。在我体验了 OpenSuSE 之后，我被它文档上的 Install software via 1-click 所惊艳（当时年轻）。

如我们找到了中文输入法：Fcitx （https://zh.opensuse.org/Fcitx），文档上包含了各种的介绍、如何安装，以及一键安装 —— 现今的 macOS 和 Windows 似乎也没有这样的功能。

交互式

在各类 PAAS 服务流行的今天，交互式的 API 体验已经成为了一个主流的方式。进细一步地，我们可以

• 低配置/零配置。人们为了灵活性而引入的各种配置本身是反人性的，大部分的配置应该是内置的，不应该由普通的开发者来配置。
• 声明式使用。即 API 应该尽可能简化，只需要简单的声明即可使用。
• 可交互文档。如 Swagger 可以在线尝试 API。
• 沙盒及产品环境。即提供一个在线的类可编程环境。

最典型的一些例子就是现代化的编程语言里提供的 Playground，如 Golang 和 Rust 都提供了 Playground。它可以让开发人员查看文档，同时运行应用的代码，还能修改代码并运行。

触点

触点是指如何去提供加深与开发者的关系。虽然有一个更专业的名称是『开发者关系』，但是它有一个更复杂的模型。这里就简化为触点，意思就是如何与开发者进行接触的点：

• 内容/文章
• 演讲/分享
• Hackathon/黑客松
• 论坛。只在形成一定规模时才考虑

从某种意义上来说，它是叫推广，但是呢，从个人的角度来看，触点这个用法比推广好得多 —— 触点可以让你意识到：现有的机制是不是无法连接到更多的开发者。

支持

这部分就是对于开发人员的支持了，每个人也都非常熟悉：

• 问题反馈渠道
• 问题反馈与响应
• 开发者即服务。源自我之前的一篇文章《开发者即服务》，意指开发者一对于指导问题。
• 开发者社区。

再说说开发者即服务，是（Developer-as-a-Service）的，亦可称为 “按需即用的开发者”。即当开发者使用某一工具、库，遇到任何相关的问题，可以随时找开发者为我们提供服务。哪怕是使用者使用了我们的 A 框架，但是遇到 B 框架有问题，他/她们也会觉得 A 框架有问题 ——因为 A 框架的开发者们是一种服务，一种开箱即用的服务。

度量开发者体验

考虑到度量开发者体验是一个复杂的问题，这里只简单列一下我所认为的两个易于度量维度：

• 首次运行所需时间
• 文档触达速度

其它的则是常规度量指标，以及对于开发者门户的度量。

首次运行所需时间

首次运行所需时间即开发人员从接触到创建第一个可运行的应用或者测试等所需的时间。

它可以让我们关注于：

• 设计最小的使用步骤
• 提供更好的 Get Started 设计
• 提供有限次数限制的 Demo Token。
• 更快的体验速度。对于下载服务，采用 CDN，适用于国内网络的下载机制。
• ……

这个指标体系可以帮助我们，理解开发人员在过程中遇到的过程痛苦。

文档触达速度

文档触达速度，即从修改完文档到所有开发人员可见所需的时间。

我们最常见的一个例子是 GitHub Pages，当我们更新完文档时，它可以实现分钟级的部署。这个维度的指标的目的主要是：

• 有意识地加快文档更新过程
• 让经常出错的问题可以快速更新
• 提醒开发人员修复了哪些问题

它可以让问题的反馈快起来。

常规度量指标

接下来，就是我们常见的一些指标，受限于框架和 SDK 等的不同会有些变化 ，典型的如：

• API 响应时间
• API 出错率
• API（可选），『每周活跃调用者数』、『API 响应时长』

对于开发人员，可以展示 API 情况的 dashboard，用于展示 API 服务的当前状况，如 GitHub Status。这样一来，就不需要再回答 API 是否挂了的问题。

开发者门户成熟度模型

在编写这篇文章的过程中，刚好看到了一篇对于门户的度量模型，《How Mature Are You? A Developer Experience API Maturity Model》简单地翻译了一些国内适用的部分（详细见原文）：

Level 1	Level 2	Level 3	Level 4
封闭的系统	门户是自服务的，但是不连贯的	完全自服务	可个性化的统一门户
文档缺乏成功调用 API 的信息	1 天内可以调用 API	10 分钟内可以调用 API	分钟级 API 调用
API 和功能没有正确对应	快速开始指南、修改日志和教程	提供沙盒和生产环境	认证流程
响应问题需要一周的时间	交互式文档	代码示例和库
	问题在 2 ~ 3 天内被回答	24 小时回答问题

如何提升开发者体验

从个人的角度来看，提升开发者体验是一个相对麻烦的过程。除了上述的两个指标之外，我觉得还有两种方式可以帮助提升开发者体验：

• 竞品对比。
• 新用户引导流程。

嗯，基本上和用户体验是类似的。

竞品对比：看齐

竞品对比，主要是通过与类似产品的对比，让自己与业内保持一致的水准。

如下是 Rust 和 Golang 的对比（只选取部分，出自于《android Go vs. Rust: Features, Similarities & Differences》）

	Rust	Golang
性能	高效能，比Swift语言快一点	GO和Java的性能不及Rust
方便性	零成本运行时抽象，非常容易且安全地用于内存等处理	使用和管理容易
易于学习	需要花时间来学习和掌握用于内存管理的语言抽象	有完整的开发文档，大量的用户社区
发展速度	与Go程序相比，RUST的编译时间更长	既简单又快速
并发与并行	RUST没有具体的并发或异步操作。	Go 具有例程（轻量级线程）和通道（go例程的通信机制），可简化应用程序的创建过程。具有本机测试机制，可在运行时发出警告。

通过这样的对比，从其它产品学习。

新用户引导流程

站在开发人员的角度出发，梳理新用户从使用过程中的痛点问题。一个详细的例子可以见：Onboarding journey

其它

PS：一不小心就把文章写长了……。

欢迎在评论区进行交流

开发者关系与布道师

这是两个岗位或者角色：

• 开发者关系，主要是要与身为开发者的用户们建立起良好的关系。
• 布道师， 将自己热爱与信仰的技术，持续不辍地传递。

对于以 SDK、云服务等为主的公司而言，他们都会通过这与之相似的岗位来建立与开发者的联系，从而提升开发者体验。

相关资料

• 《Understanding a Path》
• 《APIMatic》 构建 Developer Experience Portal SAAS 服务
• 《Backstage》 开源 Developer Portal 构建工具
• 《活文档：与代码共同演进》如何让文档活起来
• 《How Mature Are You? A Developer Experience API Maturity Model》