“这只是一个小小的改动。” – 我，2017 年 1 月.

在过去一年多里，MDN 网页文档 团队一直在为我们的参考页面设计、构建和实现交互式示例。 这样做的目的是让 MDN 能够更好地帮助“行动导向型”用户：那些喜欢通过查看和玩弄示例代码来学习，而不是通过阅读来学习的用户。

我们刚刚完成了为 JavaScript 和 CSS 参考页面添加交互式示例的工作。 这篇文章回顾了这个项目，看看我们是如何走到这一步的，以及我们在过程中学到了什么。

第一个原型

该项目最早在 2016 年底发布的 MDN 产品策略 中进行了概述。 我们在 MDN 邮件列表中讨论了一些想法，并开发了一些原型。

JS 编辑器看起来是这样的

CSS 编辑器看起来是这样的

我们希望这些示例——尤其是 CSS 示例——能向用户展示一个项目可以接受的不同语法类型。 在早期的原型中，我们使用自动完成功能来实现这一点。 当用户删除分配给 CSS 属性的值时，我们会显示一个自动完成弹出窗口，列出不同的语法变体。

第一轮用户测试

2017 年 3 月，Kadir Topal 和我参加了由 Mark Hurst 主持的第一轮用户测试。 我们从用户测试中学习了很多东西，包括关于我们的原型，以及用户想要看到什么。 我们了解到用户想要示例，并且希望示例易于找到。 用户也喜欢交互式示例。

但自动完成功能作为展示不同语法形式的方法并不成功。 它不为人知，即使那些偶然触发它的人似乎也不明白它的用途。

特别是对于 CSS，我们仍然想要一种方法来向读者展示一个项目可以接受的不同语法类型。 对于 CSS 页面，我们已经在页面中包含了一个代码块，其中列出了语法选项，如下所示

transform: matrix(1.0, 2.0, 3.0, 4.0, 5.0, 6.0);
transform: translate(12px, 50%);
transform: translateX(2em);
transform: translateY(3in);
transform: scale(2, 0.5);
transform: scaleX(2);
transform: scaleY(0.5);
transform: rotate(0.5turn);
transform: skew(30deg, 20deg);

我们看到一种我们非常喜欢的用户交互方式，即读者会将此代码块中的行复制到编辑器中，以查看效果。 所以我们想到将此代码块与编辑器结合起来。

在这个下一个版本中，你可以从下面的代码块中选择一行，该样式将应用于上面的元素。

现在回顾这个原型，有两件事很突出：第一，我们最终发布的基本交互模型已经到位。 第二，虽然我们在这个阶段之后所做的更改本质上是关于样式的，但它们对编辑器的可用性产生了巨大的影响。

建立基础

在那之后的一段时间里，进展并不大，因为我们的前端开发人员正忙于其他项目。 Stephanie Hobson 帮助改进了编辑器设计，但她同时也参与了 MDN 文章页面的全面重新设计。 6 月，Schalk Neethling 加入团队，专门负责这个项目。 他为编辑器建立了一个坚实的基础，以及一个全新的贡献工作流程。 这将成为最终实现的基础。

在这个实现中，交互式示例维护在 interactive-examples GitHub 存储库中。 一旦交互式示例被合并到存储库中，它就会被自动构建为一个独立的网页，然后从“mdn.mozilla.net”域名提供服务。 为了在 MDN 页面中包含该示例，我们使用 iframe 嵌入交互式示例的文档。

UX 工作和更多用户测试

6 月底，我们将编辑器展示给了 Jen Simmons 和 Dan Callahan，他们给了我们一些非常有用的反馈。 JavaScript 编辑器看起来还不错，但我们仍然在 CSS 编辑器方面遇到问题。 此时，它看起来是这样的

人们不明白他们可以编辑 CSS，甚至不明白左侧是单独选择的列表，而不是单个块。

Stephanie 和 Schalk 对这两个编辑器进行了完整的 UX 审查。 我们还从 Julia Lopez-Mobilia（来自 The Brigade）那里获得了独立的 UX 审查。 在所有这些工作之后，编辑器在静态截图中看起来是这样的

然后我们又进行了一轮用户测试。 这一次，我们通过视频进行了远程用户测试，参与者通过 MDN 本身招募。 这为编辑器提供了一个紧密的反馈循环：我们可以根据用户反馈快速进行调整和测试。

这一次用户测试结果非常积极，我们决定准备进入测试版。

测试版

测试版于 8 月底开始，持续了两个星期。 我们在三个 JavaScript 页面和三个 CSS 页面上嵌入了编辑器，添加了调查，并征求反馈。 Danielle Vincent 在 Mozilla 开发者通讯 中提到了它，这吸引了数千人访问 我们的 Discourse 宣布帖子。

反馈结果非常积极：在参与调查的 159 人中，有 156 人投票希望在更多页面上看到编辑器，并且自由文本反馈非常令人鼓舞。 我们相信我们拥有良好的 UX。

JavaScript 示例和页面加载优化

现在我们有了编辑器，但实际示例却很少。 我们请 Mark Boas 为 JavaScript 参考页面编写示例，几个月后，他编写了大约 400 个精美简洁的示例。

查看 Array.slice() 的示例.

不过，我们还遇到了另一个问题：编辑器使页面加载时间过长。 Schalk 和 Stephanie 努力从架构中挤出每一毫秒的性能优化，最后，在 2017 年 12 月，我们决定发布。

我们计划在今年实施一些额外的技巧来继续改进页面加载性能，事实上，我们仍然对交互式页面的当前性能不满意。

CSS 示例

在 2018 年的前三个星期里，Schalk 和我更新了 400 个 JavaScript 页面，以 包含 Mark 的示例，然后我们开始为 CSS 页面编写示例。

我们请求帮助，Jen Simmons 在推特上发布了相关信息，三个星期后，我们的社区贡献了 150 多个示例，其中 100 多个来自一位志愿者 mfluehr。

查看 rotate3d() 的示例.

在那之后，Rachel Andrew 和 Daniel Beck 开始与我们合作，他们负责剩下的工作。

查看 clip-path 的示例.

下一步是什么？

现在，我们正在为 HTML 参考 实现交互式示例。 我们刚刚完成了一轮用户测试，结果令人鼓舞，希望很快开始编写示例。

正如我希望这篇文章能说明的那样，这个项目是由许多人贡献了各种各样的技能来塑造的。 如果你想帮助这个项目，请查看 interactive-examples 存储库 和 MDN Discourse 论坛，我们会在那里定期发布更新。