You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@apisix.apache.org by Yilin Zeng <yz...@wisc.edu.INVALID> on 2021/08/03 03:04:37 UTC
[DISCUSS] Unified Notes in APISIX Documents
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
Re: [DISCUSS] Unified Notes in APISIX Documents
Posted by Zexuan Luo <sp...@apache.org>.
> 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 <ba...@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 <yz...@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
> >
Re: [DISCUSS] Unified Notes in APISIX Documents
Posted by Baoyuan <ba...@gmail.com>.
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 <yz...@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
>