Dubbo 3 易用性升级之 Dubbo 官网大改版

kirito-moe

发布于 2022-08-29 11:09:04

1.5K0

发布于 2022-08-29 11:09:04

Dubbo3 是 Dubbo 新的里程碑，Dubbo 的生态组件（包括 Dubbo Java SDK，Dubbo Golang SDK 等）都在向 Dubbo3 的目标靠拢，在用户实践方面，包括阿里巴巴、淘宝、天猫、饿了么、工商银行、平安健康等企业都已成功升级 Dubbo3 版本，随着更多的企业和用户关注或升级 Dubbo3，整个社区对 Dubbo3 的文档的需求开始变得更加迫切，以帮助用户正确使用 Dubbo3 功能或知道如何排查遇到的问题。

为了提升 Dubbo3 文档的质量，Dubbo 社区在 6 月份中旬的时候发出了《Dubbo3 官方文档贡献者召集令》。这两个月以来，Dubbo 官网收到了近 250 个 Commit，正是因为有了社区各位伙伴的踊跃贡献，Dubbo 官方文档的结构和内容有了许许多多的改变。

apache/dubbo-website 提交活跃度

本次体验优化聚焦的关注点

1. 文档全面对齐最新 Dubbo 3 版本

Dubbo 3 作为 Dubbo 的一个里程碑版本，做了众多的优化和架构调整。在本次文档优化中，我们重点关注了这部分的文档问题，补充完善了 Dubbo 架构调整的内容、全新的应用级服务发现模型和 Triple 协议等的说明使用文档。另外我们也对一些快速开始用例和已有功能的文档做了一定的优化调整，来对齐 Dubbo 3 版本。

2. 文档架构优化，抽离出面向新手的入门文档

本次体验优化的过程中，我们把原有的文档拆分为入门文档和 SDK 文档两个部分。面向 Dubbo 的入门用户，在入门文档模块可以快速了解什么是 Dubbo、Dubbo 3 的新特性、快速开始使用 Dubbo、基于场景示例的实践等。和入门文档模块与之对应的是 SDK 手册，SDK 手册中存放了各个 SDK、工具的文档，包括了 Java SDK、Golang SDK、Dubbo Go Pixiu 等，面向想要深入了解各个 SDK 的用户。

除了总体架构的分级，我们也对 Java SDK 中一些子目录的结构进行了优化，如高级特性和用法目录下按照不同的场景分离出流量治理、诊断与调优、提升安全性等子目录。

左右滑动查看入门文档部分

左右滑动查看 SDK 手册部分

3. 搜索

Dubbo 作为一个 RPC 底层框架，提供了众多的功能，为了讲清楚功能怎么用、配置怎么配、原理是怎么样的等问题，设计了众多的文档。当前 Dubbo 的总文档数达到了一千多篇，纵使文档架构再怎么优化，大部分用户也无法很快定位到具体的一篇文档。为了解决这个问题，我们引入了 Algolia 搜索工具，优化了对应的文档抓取逻辑，期望用户可以通过关键字搜索快速找到所需要的文档。

Algolia 搜索结果示例

4. 多语言生态

在 Dubbo 的发展规划中，多语言生态是一个重要的组成部分，各个语言子社区都是 Dubbo 不可分离的一个部分。在本次文档体验升级的过程中我们也将各个子社区分散的文档进行了整合，目前大部分的文档都已经迁移到了 SDK 手册中，入门文档的部分示例也和 Golang SDK 联合做了适配。

5. 异常链接修正

Dubbo 官网在历史上经历过好几个版本的大的迭代，很多网页的跳转链接存在着失效的问题，给浏览者带来了很不好的体验。在 dubbo-website 的 issue 列表中也有很多关于外链失效的反馈。为了从根本上解决这个问题，我们在 GitHub Actions 工作流中引入了基于 htmltest 的链接校验逻辑，在每次提交的时候都会检查页面上的链接是否都还是有效，如果失效的话会有对应的报错报告，以此来确保跳转都是有效的。在第一次整体调整的过程中，我们一共修复了 600+ 个链接失效问题。

规划中的内容

1. Dubbo 3 源码导读

Dubbo 3 作为 Dubbo 的里程碑版本做了很多的技术架构调整，为了让社区的小伙伴更容易理解 Dubbo 的原理设计，Dubbo 社区在规划完成新版的代码导读系列，预计在近期会和大家见面。

2. 使用 FAQ 文档

Dubbo 作为一个 RPC 框架，和开发态、运维态的工作都极为紧密，在使用 Dubbo 的过程中难免会遇到非预期的报错，但是苦于对源码不够熟悉无法进行高效的排查。Dubbo 3 将全新升级 FAQ 文档机制，在报错的时候自动链接到官方文档中对应的 FAQ 文档，提高异常的排查效率，提升总体使用体验。

写在最后

本次文档的优化只是 Dubbo 在易用性体验优化上的一个开端，由于 Dubbo 官方文档的数量众多，难免存在疏漏的地方，我们欢迎大家持续对包括 Dubbo 官方文档在内的 Dubbo 易用性体验提出问题建议（直接提交 issue 就可以啦）。在未来我们也将持续投入在 Dubbo 易用性优化的部分上，让 Dubbo 能被更多的人更容易地用上、用好。