[译文] 我们如何重建 Shopify 的开发者文档

详细了解我们为开发者提供更好体验做了哪些工作。

本文 2022 年 5 月 24 日首发于 Medium · 查看原文 

今天，Shopify 重新发布了开发者文档。这是一个漫长而复杂的项目，需要与公司内多个 UX 和开发部门的合作，很高兴看到这个项目的成功上线。我有幸从头到尾参与了这个项目，所以跟大家分享一下我们在这个过程中所积累到的一些经验。

当然，最终改版后的好坏是取决于数千名社区开发人员的实际体验。因为我们不确定是否真的达到了最初设定的目标。所以在接下来的一段时间里，我们会持续收集用户反馈，很乐意倾听你们的反馈。

下面先分享这次改版的的相关背景信息：为什么我们需要改版，以及我们如何决定改版的方案。

与我们之前在 Shopify 推出的项目一样，Shopify 开发者文档将随着我们更深入地了解用户而不断优化、迭代。其中很重要的一点是我们要试图在项目前期就去了解什么因素造就了出色的开发人员体验。

为什么我们需要改版？

首先，回到最初的出发点。用户在 Shopify 开发者文档里想要解决什么问题？

现在有超过一百万家企业在 Shopify 上运营，而且每家企业都有独特的需求。Shopify 开箱即用地解决了他们许多最棘手的业务问题，但它无法满足所有人的要求。其中一个解决方式是大型第三方开发者社区，开发者们主动构建应用程序、主题和其他插件来为商家解决问题。他们的辛勤工作使 Shopify 足够灵活且能适应你能想到的任何特殊情况。

Shopify 在过去几年中增长了很多，但我们发现开发者文档却发展缓慢。逐渐暴露出各种各样的问题：

• 教程和操作方法与参考文档耦合在一起。就像使用一个不区分药材成分和服药说明的处方。虽然有时这是正确的选择，但就我们而言，这导致了日益复杂的问题，使得文档更难维护。现在我们还没有完全解决这个问题，但是即将要进行的新网站有要有更好的处理方式。
• 旧的网站结构嵌套非常深。开发者很难自主地发现到新的、有用的功能。以 Kit 为例，商家可以在其商店中安装对话机器人以自动执行常见任务。这是 Shopify 的一项强大功能，开发者可以通过各种方式对其进行扩展。但是，你可能还不太了解 Kit，因为它只显示在 “嵌入式​​应用程序” 菜单的第三个子级里面。（为什么放在那里？没有人知道。）
• 插件/主题开发文档在 Shopify 帮助中心中混乱不堪。帮助中心的主要工作是帮助经营 Shopify 商店的企业主。而专注于与底层 Shopify API 的开发者内容有时不太合适。Shopify 商家和开发者有时也有相关的需求 — — 而且很多商家自己编写代码！ — — 但每个类型的用户所关注的文档是不同的。我们希望通过拆分不同的用户关注点来建立我们的开发者文档平台，以适应未来的发展和演变。

浏览开发者文档网站时可以看到其中一些痛点。还有一些是公司内部问题 — — 任何快速发展的公司都会有的内部矛盾和压力。这两种问题都使维护文档变得越来越难，更不用说为未来发展它们了。

事实上，我们的开发者文档在我们的社区年度调查中得到了相当高的评价。没有需要立即解决的大问题。但凭着经验，我们可以看到即将出现的问题。难以维护的文档很快就会过时、重复和变得杂乱无章。所以我们希望尽快解决这些问题。我们知道我们需要做一些事情。但是，具体是什么？

内容策略

我开始尝试了解我们之前的迭代历程。我们的目标是了解现状，了解工作的范围，并开始将重点聚焦到可管理、可交付的项目上。

我拿出了买来很久的《Content Strategy for the Web》，作者 Kristina Halvorson 和 Melissa Rach。这是关于设计方法的权威书籍之一，里面主要是做好内容策略的一些方法。

这里没有足够的空间来讨论走查内容策略方法的所有细节，但里面包含了手动梳理代码库、API 抓取以及查阅内部分析报告。我们花了几周时间，整理出了一个大型表格，可以作为我们定量分析的报告。

总的来说，我们这次走查任务发现了 2,868 页与 Shopify 的开发者社区有关的材料。其中包括以下内容：

• 我们的帮助中心有数百页的说明文档；
• 我们有数百页 API 参考文档。（在大多数情况下，这种详细描述特定 API 的 页面 是直接从实际 API 自动生成的，而不是由我们的技术团队手动填写的）；
• 我们的合作伙伴博客上有 800 多篇文章，其中许多涉及开发主题；
• 我们拥有 Shopify 开源设计系统 Polaris ；
• 我们拥有大约 500 个 Github 开源库。

通过拿各种 URL 来做数据分析以及查看其 git 提交历史，我们就能继续丰富前面提到的定量分析报告。

我们开始看到一些非常明显的用户行为：我们的文档中哪些部分被频繁迭代、哪些部分最受用户欢迎、哪些在常被搜索。我还按类型（自动生成的API 参考文档或人工撰写的指导内容）和页面类型（主题、应用程序、店铺设计）对页面进行了分类。

在这一点上，我们觉得我们有了一份很清晰的定量分析报告，但这些内容只能让你了解当前的情况。为了弄清楚我们需要做出哪些改变，我们需要与用户建立联系。

用户研究

为了以更有条理的方式解决我们的问题，我找了我们的用户体验研究团队帮忙。在 Shopify 工作的一项 “福利” 是可以接触到世界级的 UX 研究人员，他们喜欢解决这些棘手、模棱两可的问题。

对于这个项目，我们进行了两种类型的研究：一对一的访谈，以及卡片分类练习。这两种研究方式目标都是为 Shopify 生态系统找出一个通用的心智模型。如果我们知道人们对我们平台的看法，我们就可以设计一个与人们的理解相匹配的信息架构，强化他们已经知道的东西，并尝试去填补未知的知识。

用户访谈

该项目的用户体验研究员 Andrew Rajaram 设计了访谈流程并负责了大部分采访。我们邀请了两个小组进行访谈：

• 现有的 Shopify 合作伙伴，他们已经在平台方面拥有丰富经验；
• 以前从未使用过 Shopify 的开发人员。

我们还平衡了性别代表、加入了来自不同的国家和企业规模的人员名单，包括独立的自由职业者到在大公司工作的人。

Andrew 制定了一个脚本，与每个受访者进行了讨论，这样我们就可以确保关键问题不会被遗漏。我们通过视频聊天安排了每个小时的采访。在每一次采访中，都有三个人参与，分别是被采访者、采访者和一名记录员。

结论1：大多数开发人员都想边做边学

虽然肯定有一部分开发人员在开始他们的开发过程之前会通读文档，但我们采访的大多数人都喜欢快速开始做一些尝试，看看他们能走多远，边做边查阅参考资料和教程。

网络上已经有关于这个现象的详细研究过程和报告，确定开发人员会采用 “系统化” 或 “机会主义” 方法来使用开发者文档。系统化的开发者喜欢先阅读，再进行编码。机会主义者则尽可能快地开始编写代码。值得注意的是，这两种风格都与 “更好” 的代码或更成功的结果无关。但这确实意味着开发者文档需要对两种类型的使用者都可以访问和有用。

结论2：对法律文件的兴趣与公司规模成正比

在中型及以上的公司中，受访者通常会询问更多有关 API 服务条款、隐私政策、服务级别协议以及其他法律或合同文件的信息。这对于这些类型的公司尤其重要，因为他们经常需要给对许可和用户隐私有自己要求的客户工作。

这是我们从访谈过程中发现到的有价值的新见解之一，以往的用户研究没有提到相关内容。我们发现了这一点，这确实是有必要的。因此，新的开发者文档将 Shopify API 服务条款以及用户隐私和法规的理念放在首位。

结论3：文档需求随时间而变化

这听上去是显而易见的道理，但正是这个观点使我们不再围绕用户角色来编排开发者文档。

通常，UX 设计师通过用常见的角色来划分典型用户：例如，如果您正在做一款汽车 4S 店的应用程序，您可能会为在停车场上卖车的人（销售员）和在服务区工作的人（修理工）设计不同的使用流程。这种方式使你能够针对常见的使用流程和用户需求做出精简而有效的概括。

这种明确的角色分工在软件开发中不太普遍。比如在一家大型电商公司里，可能有需要了解商业机会的副总裁，需要了解平台高级技术能力的首席产​​品官，以及一个需要详细了解 API 使用的开发团队。通常这些信息需要重叠和模糊，因为有时候这些 “角色” 实际上都是一个人，只是他会在电商产品发展过程中经历不同的角色阶段。

这让我们相信，根据角色特点来编排文档不是一个好做法。人们不是 “初学者” 或 “专家” ，他们是有问题要解决的人。我们无法根据（有时候甚至是错误的）他们在任何时候想要做什么来假设他们的想法或将他们归类。

这一发现使我们朝着更扁平的信息结构发展，增加了更高级别导航的主题数量。我们的假设是，这使普通用户更轻松地浏览和发现我们的文档内容，而有明确目的用户可以更快地深入文档以获取到他们具体问题的答案。

卡片分类法

我们的下一步是进行卡片分类实验。我们为开发者提供大约 50 张卡片，每张卡片上都有一个文档或主题的名称。我们要求他们对这些卡片进行分类，将属于同一堆的卡片放到一堆中，然后给每一堆卡片命名。我们想看看人们在分类 Shopify 平台的信息中是否能找到相同的心智模型。

最终的结果惊人地一致。大部分情况下，各组的排列会是这样：

• 平台基本信息；
• 法律要求和法律责任；
• 完整的参考文档；
• 操作指南、教学材料、教程；
• 软件工具、库和 SDK。

这个结果真正有趣的是它与我们同时进行的关于 DITA 的其他一些研究结论相匹配。DITA 是一种基于 XML 语言和信息分类的资料开发方法，最初由 IBM 在 2000 年代初开发，现在是一个开放标准。DITA 将文档分为三大类：

• 概念（你需要了解的上下文信息）
• 参考资料（你正在使用的东西的详细描述）
• 任务（根据你对概念和参考资料的了解，你可以采取的行动）

理论和真实行为之间的重叠是令人诧异的。人们正好一直在寻找：

• 背景信息和背景（概念）；
• Shopify 功能的综合 “字典”（参考资料）；
• 实施常见工作流程的指南（任务）；
• 帮助他们更快完成工作的工具。

DITA 的核心规范并未涉及“工具”，但类型足够清晰，我们决定可以开始原型设计并尝试围绕这些结论改进信息架构。几个月后的结果就是你今天所看到的。

结果

如你所见，新网站的架构非常接近我们从用户研究中获取到的资讯。五个大分类是概念、文档、教程、工具和社区（其中最后一个区域目前仅链接到 Shopify 的其他部分，例如我们的开发者论坛和合作伙伴学院）。

随着今天的发布，Shopify.dev 已成为我们所有面向开发人员的文档和指引内容的主要来源，我们看到 Shopify 的开发人员体验有很大发展和创新机会。

我们非常有信心，这种新的信息架构使我们能够以有组织和可扩展的方式继续发展。但是有用吗？易理解和使用吗？能够快速找到目标吗？足够清晰吗？这个判断最终取决于你。我们很想听听你们在留言中想法。

原文：How we rebuilt Shopify’s developer docs

翻译：李瑞东