Dubbo 3's Ease of Use Upgrade: A Major Revision of Dubbo's Official Website

Dubbo 3 is a new milestone for Dubbo. Dubbo's ecological components (including Dubbo Java SDK, Dubbo Golang SDK, etc.) are moving closer to Dubbo 3's goal. Enterprises such as ICBC and Ping An Health have successfully upgraded the Dubbo 3 version. As more enterprises and users pay attention to or upgrade Dubbo 3, the entire community's demand for Dubbo 3 documentation has become more urgent to help users use Dubbo correctly. 3 features or know how to troubleshoot problems.

In order to improve the quality of Dubbo 3 documentation, the Dubbo community issued the "Dubbo 3 Official Documentation Contributor Calling Order" in mid-June. In the past two months, Dubbo's official website has received nearly 250 Commits. It is precisely because of the active contributions of all partners in the community that the structure and content of Dubbo's official documents have undergone many changes.

apache/dubbo-website submission activity

The focus of this experience optimization focus

1. The documentation is fully aligned to the latest Dubbo 3 version

As a milestone version of Dubbo, Dubbo 3 has made numerous optimizations and architectural adjustments. In this document optimization, we focused on the documentation issues in this part, and supplemented and improved the content of the Dubbo architecture adjustment, the new application-level service discovery model, and the description and usage documents of the Triple protocol. In addition, we have also made some optimization adjustments to the documentation of some quick start use cases and existing functions to align with the Dubbo 3 version.

2. The document structure is optimized, and the introductory document for novices is extracted

In the process of this experience optimization, we split the original document into two parts: the introductory document and the SDK document. For introductory users of Dubbo, in the introductory documentation module, you can quickly understand what Dubbo is, the new features of Dubbo 3, quickly start using Dubbo, and practice based on scenario examples. Corresponding to the introductory documentation module is the SDK manual. The SDK manual stores the documentation of various SDKs and tools, including Java SDK, Golang SDK, Dubbo Go Pixiu, etc., for users who want to know more about each SDK.

In addition to the classification of the overall architecture, we have also optimized the structure of some subdirectories in the Java SDK. For example, in the Advanced Features and Usage directory, subdirectories such as traffic management, diagnosis and tuning, and security enhancement are separated according to different scenarios.

Getting Started Documentation Section

SDK manual section

3. Search

As an RPC underlying framework, Dubbo provides many functions. In order to clarify how to use the functions, how to configure the configuration, and what the principles are, many documents are designed. At present, the total number of documents in Dubbo has reached more than 1,000. Even if the document structure is optimized, most users cannot quickly locate a specific document. In order to solve this problem, we introduced the Algolia search tool to optimize the corresponding document crawling logic, hoping that users can quickly find the required documents through keyword search.

Algolia search result example

4. Multilingual Ecosystem

In Dubbo's development plan, the multilingual ecology is an important part, and each language sub-community is an inseparable part of Dubbo. In the process of this document experience upgrade, we have also integrated the scattered documents of each sub-community. At present, most of the documents have been migrated to the SDK manual, and some examples of the introductory documents have also been jointly adapted with the Golang SDK.

5. Abnormal link correction

The Dubbo official website has experienced several major iterations in history, and the jump links of many webpages have problems of invalidation, which brings a very bad experience to the browser. There is also a lot of feedback on the failure of external links in the issue list of dubbo-website. In order to fundamentally solve this problem, we have introduced link verification logic based on htmltest in the GitHub Actions workflow, which will check whether the links on the page are still valid each time a submission is made. If it fails, a corresponding error will be reported. report to ensure that the jumps are all valid. During the first overall adjustment, we fixed a total of 600+ broken links.

What is planned

1. Dubbo 3 source code guide

As a milestone version of Dubbo, Dubbo 3 has made a lot of technical architecture adjustments. In order to make it easier for the community to understand the principle design of Dubbo, the Dubbo community is planning to complete a new version of the code guide series, and it is expected to meet you in the near future.

2. Use the FAQ document

As an RPC framework, Dubbo is very closely related to development and operation and maintenance. In the process of using Dubbo, it is inevitable to encounter unexpected errors, but due to the lack of familiarity with the source code, efficient investigation cannot be carried out. Dubbo 3 will upgrade the FAQ document mechanism, and automatically link to the corresponding FAQ document in the official document when an error is reported, improve the efficiency of abnormal investigation and improve the overall user experience.

write at the end

The optimization of this document is only the beginning of Dubbo's usability experience optimization. Due to the large number of Dubbo official documents, there are inevitably omissions. We welcome everyone to continue to make suggestions on Dubbo's usability experience, including Dubbo's official documents. Problem suggestions (just submit an issue directly). In the future, we will also continue to invest in the optimization of Dubbo's usability, so that Dubbo can be more easily used and used by more people.

Click here to go directly to Dubbo's official website.