提供丰富的开发者体验对于构建成功的开发者社区至关重要。

优秀文档的基本特征：

●       上下文：开发者文档必须为开发者提供上下文，不仅要描述什么是重要的，而且要描述为什么它是重要的。简单地（以IBM how-to的风格）生成一系列代码片段，没有任何解释，并不足以帮助开发人员理解他们正在阅读的内容在他们正在创建的内容的上下文中很重要。

●       适用性：作为充足上下文的补充，文档应必须立即适用于开发者。一旦他们理解了产品的某个特定方面的重要性，他们即可通过代码片段和示例将这些知识应用到应用开发中。

●       针对性：编写主题内容同样必要，以便能针对社区中特定角色的需求。主题内容主要受众虽然可能还是开发者，但必须考虑到其他团队和角色，如产品所有者和运营人员。此外，开发者本身也有子集，例如，前端和后端开发人员有不同的。

为方便理解，我们以Stripe的实践为例：

●       Stripe提供易于使用的前端组件、SDK和API，用于访问各种不同的支付方法和渠道。从主题的角度来看， Stripe对其文档进行定制和细分，针对不同类型的开发者提供适用的文档，并且在整个过程中提供重要的上下文。

●       例如，开发者可能不熟悉支付卡行业（PCI）法规，但Stripe通过在教程和参考文档中加入重要信息来弥合这一差距。这减少了开发人员需要从其他地方阅读更多细节。对于大多数组织而言，一大挑战是处于PCI法规之外，而Stripe在信息传递时提供了恰当的上下文。这使开发者能够获取帮助其成功的具体细节内容，并了解支付卡数据的相关保障措施。

 

Stripe还旨在针对不同类型的开发者提供与他们的角色和需求相关的组织良好的文档。这样， Stripe确保开发者只需要阅读适用于其所需内容。例如，API文档针对Checkout 和 Elements等前端组件完全独立分开。SDK文档在iOS和Android之间也是类似的细分。关于向支付工具收费的信息（收集支付细节后实际执行支付的步骤）甚至在其自己的页面上，因此实现Checkout的前端开发者不需要搜索变化的信息，可以只关注Checkout本身。

Stripe提供的代码示例非常适用，因为其开发文档是根据开发人员的API密钥自动定制的(前提是开发人员登录到Stripe站点)。当开发人员在查看API文档时执行cURL命令，不需要进行任何修改。

 

注意：

●       任何时候应切记受众不是统一的。开发者的形式和规模各不相同。应根据技能子集定制文档来满足不同群体的需求。

●       受众可能不是某一特定主题的专家，他们对细节的需求很低；他们需要的是背景。为他们提供适当的背景信息，这样他们就能充分了解你的API所涉及的主题、产品或行业。

●       确保你所传达的内容是适用的，通过给出具体例子，帮助受众以最小的努力实现关联并应用。

 

在决定使用的工具时，您和您的团队有许多项目、产品和服务可供选择。

一个重要考虑方面是文档。但我们如何判断什么是好的文档呢?

一个工具可能提供了令人兴奋的特性，但是可能缺少文档的开发者经验。

在评估一个新工具时，开发者体验与所提供的特性一样重要。

1.      加入并开始

当您学习新的工具，入门指南通常是您阅读的第一个文档。

糟糕的体验很可能会让任何偶然的读者无法进一步探索。第一印象很重要，因此在评估文档入门体验时，需要考虑四个要素：

●       提供自助服务选项

尝试 《入门指南》通常是开发人员评估新技术工具的第一个要点。

一些工具（特别是在SaaS领域）需要先从前端开始，引导您开始第一步后继续完成后续步骤。

在任何一种情况下，优先使用允许您创建帐户和测试的工具，而不需要预约销售代表或填写过多的表格。这与文档没有直接关系，但是通常只有通过这个过程后才能查看文档，这使得评估工作变得非常困难。

●       入门需要的时间

当存在多个选项，那么遵循入门指南从开始到最后获得结论所花费的时间是一个重要的衡量标准。

虽然实际时间在很大程度上取决于教程的复杂性，但对于类似的工具或指南，较短的时间表明团队已经付诸努力减少障碍、测试步骤，并检查他们使用的语言是否清晰。

●       真实世界的示例

入门指南往往侧重于简单和高效，让工具看起来“容易”使用。

然而，如果指南中的示例和步骤完全脱离 “真实世界”场景，那么它还是一个好的入门指南吗?

●       依赖关系和先决条件

某些编程语言以具有深刻而复杂的依赖树而著称。这意味着一些项目可能会利用来自第三方的代码（这是常见的），因此工具也会继承对应的依赖关系。

遵循入门指南不应让您陷入澄清相互冲突的依赖版本或未记录的先决条件。如果是，这表明文档的作者并没有站在“普通的”新用户从零开始的视角。

理想情况下，项目应该使用最流行的或支持度最高的（例如，LTS ）语言和操作系统版本。如果不是，这可能表明他们对开发或特定平台缺乏有意义的承诺。

至少，文档应该说明您需要哪个版本，并大致了解什么时候需要支持更新或更流行的版本。

2.      持续的客户旅程

一个好的入门指南对于任何你正在评估的项目都是一个很大的加分项，但是入门指南很少能帮助你将任何东西应用到真实的生产应用中。

创建文档最困难的部分之一是带读者踏上这一关键旅程，这通常是大多数人对文档感到沮丧的地方。有些项目比其他项目有更清晰和定义更明确的用例（例如，支付API和CMS ），但是有一些通用的东西需要注意。

一个好的入门指南应该为您接下来将要继续的页面或路径提供建议。这些可能是通用的，例如工具的关键组件，寻找特性的进一步信息，或者遵循基于用户研究的典型用例。

文档几乎不可能满足您可能拥有的所有用途，但它可以帮助您收集所需的知识。

3.      示例代码

开发人员通常不会彻底阅读文档，取而代之的是浏览代码示例。好的文档的结构是为了确保重要的内容围绕着代码示例，让开发者有更多的机会注意到它。不完整或不起作用的代码示例通常是任何阅读文档的人的烦恼来源。

●       不同类型的代码示例，在每种情况下，它们的目的都应该是明确的。

有些代码示例是教程或指南的一部分。开发者应按遵循特定的顺序并构建完整的代码片段方能达成预期目的。在这些情况下，示例应该告诉开发者需要知道的一切信息，而不应仅仅是假设例子。

●       一些代码示例是说明性的，以显示概念或实现细节。

这意味着如果不替换占位符值或额外代码，它们就无法工作。文档应明确这些内容，并告诉开发者需要做什么才能使它们可用。

●       虽然并不总是必要的，但文档应该解释或向开发者展示代码示例的预期输出，以便他们知道代码是否被成功实现。

●       如果一个项目支持多种编程语言或实现选项，那么文档应显示所有这些语言或实现选项的代码示例。这需要巨大的投入，但针对最广泛使用的选项的示例是必不可少的。如果没有示例代码，其他支持的选项的也应提供充分的指导说明。

4.      参考 - API文档

参考文档的作用一般是填补文档空白，主要包括API端点和函数文档、架构说明以及需要开发者了解的其他方面。

●       首先，是否有参考文档，或者您需要遍历代码库才能找到它？

●       如果参考文档存在，它是否完整或有用？一些项目通常会自动生成参考文档，这很高效，但此类描述通常来自代码注释，代码注释对读者并不总是有用的。

●       参考文档可以比其他文档更抽象，因为它描述了项目的各个部分，而不是如何使用它们。然而，好的参考文档应解释API的定义以及它是如何工作的。

Stripe API文档是自动生成可用且有用API文档的范例(使用高度定制的工具)。

5.      语言

好的语言是一个很大的话题，它不一定会影响项目的质量，单它可以表明团队在背后所辅助的额外努力。

可接受的文档应无拼写错误和其他排版错误。良好的文档应使用一致的语调、术语和风格。在这些方面，什么是“正确”会有一些个人不同见解，但一致性是关键。

6.      加分项：好的文档体现团队的重视程度

一些加分项虽然并不完全符合前述的任何部分，但表明团队对细节的额外关注。

●       文档看起来如何？一些看起来非常棒并使用Web开发中最新技巧呈现的文档可能不等同于有用和可用，但如果两者兼备，那无疑是最为理想的结果。

●       文档更新的频率是多少？不进行定期文档更新应当充分的理由，例如项目过时或文档无问题（ problem-free ）。

参考：How Great Ddocumentation

Improves Your Developer Experience（https://openchannel.io/blog/how-great-documentation-improves-your-developer-experience）