> we expect community users to visit and read the documents from Apache APISIX > website rather than GitHub repository.
"Expect" is not a good solution. > 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. It already happened in APISIX, see https://github.com/apache/apisix/pull/4660 > Unfortunately, there is no perfect solution to satisfy both website readers > and GitHub readers. > My proposal is to sort and replace all existing plain text notes with > Docusaurus admonitions Why not do this via generating website? Baoyuan <baoyuan....@gmail.com> 于2021年8月3日周二 上午11:32写道： > > I agree with using Docusaurus warnings to sort and replace all existing > plain text comments. > > Also is it possible to make the links[1] more prominent or higher in the > README file of APISIX ？ > > [1] https://apisix.apache.org/docs/apisix/getting-started/ > > Best Regards > > Yilin Zeng <yzen...@wisc.edu.invalid> 于2021年8月3日周二 上午11:04写道： > > > 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 > >
