来自OpenTelemetry文档可用性调查的见解
博客文章在发布后不会更新。这篇文章已经发布一年多了，其内容可能已过时，部分链接可能无效。在依赖任何信息之前，请务必核实。
OpenTelemetry 端用户 SIG 最近对社区进行了一项调查，以了解 OpenTelemetry 的文档在多大程度上对用户友好。在之前的调查中，三分之二的受访者表示，全面的文档是他们开始使用 OpenTelemetry 时最希望拥有的顶级资源。因此，我们决定深入研究一下。
文档可用性调查询问用户在哪里查找 OTel 文档、他们希望在文档中看到更多什么内容，以及他们如何评价文档的当前状态。我们收到了 48 份回复，我们将利用这些回复来聚焦我们的文档工作，并在关键领域进行改进。
非常感谢所有参与调查的人！让我们来看看结果。
主要收获
- 受访者表示希望有**更多的视觉辅助**，例如图表和屏幕截图。
- 在我们询问的三种类型的文档（组件概念、安装说明和故障排除）中，**故障排除文档**被确定为最需要改进的部分。
- 当被问及他们最希望添加到 OTel 文档中的信息时，排名前几位的回复是**更多的示例**和**更广泛的覆盖**，包括深度和广度。
- Collector 文档是咨询最多的资源，这一发现与 SIG Communications 在其年终回顾中的页面浏览量分析一致。
- 经过标准化和加权后，Java 文档获得了**最高的整体评分**，这反映了最近对其组织结构进行的改进所产生的积极影响。相反，Swift 文档的整体评分最低。
- 在六个最受欢迎的文档集中，JavaScript 文档的评分**最低**。
详细见解
关于受访者
- 79% 的用户在生产环境中使用 OTel。
- 21% 的人受雇于可观测性或 APM 供应商。
- 98% 的人具有可观测性方面的先前知识：中级（60%）或专家（38%）。
问：当您查找关于 OpenTelemetry 的信息时，您主要依赖哪个来源？
- 总体而言，大多数受访者（52%）依赖 opentelemetry.io 文档。
- 处于可观测性实践早期（初学者和中级）的受访者更倾向于使用 opentelemetry.io 文档。
- 专家级可观测性实践者更喜欢代码仓库文档。
将 opentelemetry.io 作为主要信息来源的受访者
按可观测性知识水平划分
初学者 中级 专家 100% 62% 44%
文档愿望清单
问：您希望在 opentelemetry.io 中添加哪些目前尚不提供的内容？
我们要求受访者用自己的话描述他们希望添加到 opentelemetry.io 文档中的内容。我们将他们的回答大致分为六类。有些答案属于多个类别。完整回复请参阅 文档可用性调查回复。
- 更多示例：17（35%）
- 更深入或更广泛的覆盖：13（27%）
- 更好的结构：8（17%）
- 添加代码仓库文档：5（10%）
- 其他：2（4%）
- 无回复：7（15%）
问：更多的视觉辅助（例如，图表和屏幕截图）来解释 OpenTelemetry 概念会有帮助吗？
高达 81% 的受访者表示同意：他们想要更多的视觉辅助。
文档的当前状态
问：opentelemetry.io 上的当前文档在多大程度上解释了 OpenTelemetry 的不同组件？
大多数受访者认为组件概念文档的平均水平为一般，最高评分是 3。
问：OpenTelemetry 的安装说明有多么直接和用户友好？
大多数受访者认为 OTel 说明比平均水平好，最高评分是 4。具有中级可观测性知识的受访者对其评价高于专家：55% 的中级受访者将安装说明评为 4 或 5，而专家中只有 17% 这么认为。
问：故障排除部分的全面性如何？
大多数受访者认为文档的这一部分需要改进。只有 15% 的人将故障排除文档评为 4 或 5，并且他们都是中级受访者。没有一位专家级受访者将故障排除文档的评分评为高于 3。
问：您如何评价您在使用当前 OTel 文档处理以下语言和组件时的体验？
受访者只被要求评价适用于他们的文档，因此我们可以根据他们的回答推断出哪些文档集的使用最频繁。
- Collector 文档使用最广泛：77% 的受访者评价了它。
- 接下来的五个文档集在流行度上非常接近，有 50% 到 67% 的受访者评价了它们。
以下是所有语言和组件的汇总评分。当结果经过标准化和加权后，我们可以看到更多见解
- Java 文档的整体评分最高。
- Swift 文档的整体评分最低。
您如何评价您在使用当前 OTel 文档处理以下语言和组件时的体验？
语言或组件 差 一般 好 总回复数 标准化和加权 Java 3 16 8 27 7.3333 PHP 1 4 2 7 7.1429 GO 6 12 9 27 7.1111 Collector 9 17 11 37 6.8108 Python 6 17 8 31 6.7742 Kubernetes 6 20 6 32 6.3750 C++ 0 7 0 7 6.0000 JavaScript 3 19 2 24 6.0000 Ruby 1 5 1 7 6.2857 Rust 4 4 2 10 5.6000 .NET 4 8 2 14 5.7143 Erlang 1 6 0 7 5.4286 FaaS 5 7 0 12 4.3333 Swift 3 3 0 6 4.0000 总计 52 145 51
如果我们结合这些见解，我们可以看到，使用人数最多但最需要改进的文档是 JavaScript 文档。
我们应该将改进工作集中在哪里？
JavaScript 是六个使用最多的文档集之一，但其评分最低。
语言或组件 差 一般 好 总回复数 标准化和加权 GO 6 12 9 27 7.1111 Java 3 16 8 27 7.3333 JavaScript 3 19 2 24 6.0000 Python 6 17 8 31 6.7742 Collector 9 17 11 37 6.8108 Kubernetes 6 20 6 32 6.3750
了解更多
有关详细的调查结果，请参阅 文档可用性调查回复。
您的反馈至关重要
再次感谢所有参与调查的人！您的反馈对于指导 OpenTelemetry 的未来发展至关重要，并确保它能够持续满足您不断变化的需求。请通过以下渠道保持联系，并了解即将进行的调查