Hi Community, As more and more users are using Apache APISIX, documents are getting more important. A community user pointed out that the notes in Apache APISIX documents were not unified, it is inconvenient for those who prefer to read documents directly from GitHub repository.
Notes in Apache APISIX documents are split into two groups: one is written in plain text, such as ’note’ or ’Note’; the other is written in Docusaurus structure, such as ‘:::note’ and ends with ‘:::’. The first group of notes in plain text is somewhat ambiguous (i.e. it could be a note, an info, a tip, a caution, or a warning). In addition, plain text is easy to be ignored or skipped. For example, note under ‘Attributes’ chart https://apisix.apache.org/docs/apisix/plugins/serverless#attributes. The second group of notes (:::note :::) takes advantages of Docusaurus admonitions, makes it more noticeable on Apache APISIX document website. For example, note under ‘Prerequisites’ section in ‘Getting Started’ document: https://apisix.apache.org/docs/apisix/getting-started/#pre-requisites. Furthermore, Docusaurus supports 5 sorts of admonitions: note, tip, info, caution and danger, which is an ideal solution for the problem of ambiguity. For more details, Docusaurus provides usages of admonitions on its official website: https://docusaurus.io/docs/next/markdown-features/admonitions. While the second group of notes enhances user experience when reading from the Apache APISIX document website, it also creates inconvenience for those who are reading directly from GitHub repository. Since Docusaurus admonitions is not able to show up as expected in GitHub repository, as shown in here: https://github.com/apache/apisix/blob/master/docs/en/latest/getting-started.md#pre-requisites, some might recognize it as typo and create an issue or pull request trying to fix it. Unfortunately, there is no perfect solution to satisfy both website readers and GitHub readers. I took a look at other open-source projects’ documents, including Zilliz, TiDB and Rancher, none similar case was reported in their pull requests or issues. It seems like reading directly from GitHub repository is a rare case. As far as I am concerned, community users are encouraged to read from Apache APISIX document website first. When a problem is found in documents, community users can then actually dig into Apache APISIX GitHub repository to either file an issue, or submit a pull request to fix the problem. My proposal is to sort and replace all existing plain text notes with Docusaurus admonitions (i.e. note, tip, info, caution and danger) to make it more noticeable on document website, since documents under the Apache APISIX repository served as data source for Apache APISIX website, and we expect community users to visit and read the documents from Apache APISIX website rather than GitHub repository. What's your opinion? If you have better solutions, please don’t hesitate to speak up. Thanks! Regards, Yilin Zeng
