[DISCUSS] Apache APISIX Doc Maintainers Program

[Zhiyuan Ju <ju...@apache.org>]

Hi, folks,

As we all know, documentations are essential for products and users. We now
have 12 repositories[1], and according to feedback/questions from GitHub,
Slack, and other channels, most questions are about the following projects:

1. apache/apisix
2. apache/apisix-dashboard
3. apache/apisix-ingress-controller
4. apache/apisix-docker
5. apache/apisix-helm-chart
6. Plugin runners

In the past three years, community members maintained all documents with
different styles and experiences, but this led to our documentation being
too "advanced". I propose this program to avoid this case, and I hope with
Doc Maintainers' help, Apache APISIX projects' documents have unified
styles and are friendly to new and target users.

*First, who the documentation's users are?*

1. New Users: Users who know us for the first time or just a little.
2. Experienced Users: Users who rarely need documentation but could use
products very well, e.g., Product active contributors or people who know
the product codes logics better.
3. Beginner Users: Users between New Users and Experienced Users.

*Second, who is our documentation for?*

Several experienced users said that they would choose to explore code on
GitHub directly instead of searching for documentation because they know
codebases very well and know how to debug and find solutions efficiently.
For this proposal, the target users are new and beginner users.

*Program Goal*

To keep documentation:
1. Correct
2. Up to date
3. Clear
4. Friendly

*Maintainers Responsibilities*

1. Maintain Documentation Style Guide[2]. This guide is the foundation of
all documentation work.
2. Revamping the documentation.
3. Propagating the changes to the documentation to the other language
(English <-> Chinese).
4. Review changes to the documentation.
5. Ensuring documentation is updated with changes/addition of features.
6. Opening issues and delegating documentation work to the community.

*What benefits could we have from this Informal Maintainers Team?*

- Documentation will be community-driven.
- Less reliance on a couple of individuals.
- Transparency of work.
- Consistency in the documentation.
- Documentation becomes self-sustaining.

*Possible Case*

1. PR with documentation changes
1.1 Engineers should review and make sure all code changes are valid.
1.2 Notify Docs Maintainers by adding a label to that PR/Issue, like
"request-doc-maintainers". E.g.,
https://github.com/apache/apisix-website/labels/request-doc-maintainers
1.3 If this PR's documentation changes meet needs (goal and guide), doc
maintainers should approve.
1.4 We need at least two approval from maintainers to merge PR.
1.5 (Conditional) If this PR only contains English changes, Maintainers
should submit a new PR to sync changes to Chinese.

*Recommend Maintainers*

Based on my observations in the community across multiple repositories, I
recommend that we could contact these contributors when you have
documentation needs:

1. English
1.1 Navendu[3]
1.2 Avinal[4]

2. Chinese
2.1 Fei Han[5]
2.2 SylviaBABY[6]

*NOTE*
1. This program welcomes everyone involved, not limited to the maintainers
listed above. Just watch the repository, find doc-related PR/Issue and join
in. I will continue to observe the documentation contributors.
2. I was hoping to talk about Usecases, Tutorials, and Katacoda things, and
now I think it's better to achieve the agreement on the current proposal
first.

What's your opinion about the Goal and this Program?

[1] https://github.com/apache/?q=apisix-&type=all&language=&sort=
[2] https://apisix.apache.org/docs/general/documentation-style-guide
[3] https://github.com/apache/apisix/commits?author=navendu-pottekkat
[4] https://github.com/apache/apisix/pull/6610
[5] https://github.com/apache/apisix/pulls/hf400159
[6] https://github.com/apache/apisix/pull/6974

Best Regards!
@ Zhiyuan Ju <https://github.com/juzhiyuan>

Re: [DISCUSS] Apache APISIX Doc Maintainers Program

[Yeming Gu <ye...@gmail.com>]

Hi Zhiyuan!

I'm looking forward to the upgraded document, and of course I'm willing to
provide some suggestions from the perspective of newcomers.

Best Regards
Yeming Gu

Zhiyuan Ju <ju...@apache.org> 于2022年5月12日周四 17:44写道：

> Hi, folks,
>
> As we all know, documentations are essential for products and users. We now
> have 12 repositories[1], and according to feedback/questions from GitHub,
> Slack, and other channels, most questions are about the following projects:
>
> 1. apache/apisix
> 2. apache/apisix-dashboard
> 3. apache/apisix-ingress-controller
> 4. apache/apisix-docker
> 5. apache/apisix-helm-chart
> 6. Plugin runners
>
> In the past three years, community members maintained all documents with
> different styles and experiences, but this led to our documentation being
> too "advanced". I propose this program to avoid this case, and I hope with
> Doc Maintainers' help, Apache APISIX projects' documents have unified
> styles and are friendly to new and target users.
>
> *First, who the documentation's users are?*
>
> 1. New Users: Users who know us for the first time or just a little.
> 2. Experienced Users: Users who rarely need documentation but could use
> products very well, e.g., Product active contributors or people who know
> the product codes logics better.
> 3. Beginner Users: Users between New Users and Experienced Users.
>
> *Second, who is our documentation for?*
>
> Several experienced users said that they would choose to explore code on
> GitHub directly instead of searching for documentation because they know
> codebases very well and know how to debug and find solutions efficiently.
> For this proposal, the target users are new and beginner users.
>
> *Program Goal*
>
> To keep documentation:
> 1. Correct
> 2. Up to date
> 3. Clear
> 4. Friendly
>
> *Maintainers Responsibilities*
>
> 1. Maintain Documentation Style Guide[2]. This guide is the foundation of
> all documentation work.
> 2. Revamping the documentation.
> 3. Propagating the changes to the documentation to the other language
> (English <-> Chinese).
> 4. Review changes to the documentation.
> 5. Ensuring documentation is updated with changes/addition of features.
> 6. Opening issues and delegating documentation work to the community.
>
> *What benefits could we have from this Informal Maintainers Team?*
>
> - Documentation will be community-driven.
> - Less reliance on a couple of individuals.
> - Transparency of work.
> - Consistency in the documentation.
> - Documentation becomes self-sustaining.
>
> *Possible Case*
>
> 1. PR with documentation changes
> 1.1 Engineers should review and make sure all code changes are valid.
> 1.2 Notify Docs Maintainers by adding a label to that PR/Issue, like
> "request-doc-maintainers". E.g.,
> https://github.com/apache/apisix-website/labels/request-doc-maintainers
> 1.3 If this PR's documentation changes meet needs (goal and guide), doc
> maintainers should approve.
> 1.4 We need at least two approval from maintainers to merge PR.
> 1.5 (Conditional) If this PR only contains English changes, Maintainers
> should submit a new PR to sync changes to Chinese.
>
> *Recommend Maintainers*
>
> Based on my observations in the community across multiple repositories, I
> recommend that we could contact these contributors when you have
> documentation needs:
>
> 1. English
> 1.1 Navendu[3]
> 1.2 Avinal[4]
>
> 2. Chinese
> 2.1 Fei Han[5]
> 2.2 SylviaBABY[6]
>
> *NOTE*
> 1. This program welcomes everyone involved, not limited to the maintainers
> listed above. Just watch the repository, find doc-related PR/Issue and join
> in. I will continue to observe the documentation contributors.
> 2. I was hoping to talk about Usecases, Tutorials, and Katacoda things, and
> now I think it's better to achieve the agreement on the current proposal
> first.
>
> What's your opinion about the Goal and this Program?
>
> [1] https://github.com/apache/?q=apisix-&type=all&language=&sort=
> [2] https://apisix.apache.org/docs/general/documentation-style-guide
> [3] https://github.com/apache/apisix/commits?author=navendu-pottekkat
> [4] https://github.com/apache/apisix/pull/6610
> [5] https://github.com/apache/apisix/pulls/hf400159
> [6] https://github.com/apache/apisix/pull/6974
>
> Best Regards!
> @ Zhiyuan Ju <https://github.com/juzhiyuan>
>

Re: [DISCUSS] Apache APISIX Doc Maintainers Program

[Ayush Das <ay...@gmail.com>]

Hey Zhiyuan!
Agree (+1)

That a really great initiative by your side. This was definitely needed to
make everything arranged in an appropriate manner.

I was really thinking that its high time that we should now focus to make
our documentation appropriately oriented.

I will definitely add my part of contributions to make this program
successful.

Best Regards
Ayush Das<https://github.com/iamayushdas>

On Thu, 12 May 2022 at 3:13 PM, Zhiyuan Ju <ju...@apache.org> wrote:

> Hi, folks,
>
> As we all know, documentations are essential for products and users. We now
> have 12 repositories[1], and according to feedback/questions from GitHub,
> Slack, and other channels, most questions are about the following projects:
>
> 1. apache/apisix
> 2. apache/apisix-dashboard
> 3. apache/apisix-ingress-controller
> 4. apache/apisix-docker
> 5. apache/apisix-helm-chart
> 6. Plugin runners
>
> In the past three years, community members maintained all documents with
> different styles and experiences, but this led to our documentation being
> too "advanced". I propose this program to avoid this case, and I hope with
> Doc Maintainers' help, Apache APISIX projects' documents have unified
> styles and are friendly to new and target users.
>
> *First, who the documentation's users are?*
>
> 1. New Users: Users who know us for the first time or just a little.
> 2. Experienced Users: Users who rarely need documentation but could use
> products very well, e.g., Product active contributors or people who know
> the product codes logics better.
> 3. Beginner Users: Users between New Users and Experienced Users.
>
> *Second, who is our documentation for?*
>
> Several experienced users said that they would choose to explore code on
> GitHub directly instead of searching for documentation because they know
> codebases very well and know how to debug and find solutions efficiently.
> For this proposal, the target users are new and beginner users.
>
> *Program Goal*
>
> To keep documentation:
> 1. Correct
> 2. Up to date
> 3. Clear
> 4. Friendly
>
> *Maintainers Responsibilities*
>
> 1. Maintain Documentation Style Guide[2]. This guide is the foundation of
> all documentation work.
> 2. Revamping the documentation.
> 3. Propagating the changes to the documentation to the other language
> (English <-> Chinese).
> 4. Review changes to the documentation.
> 5. Ensuring documentation is updated with changes/addition of features.
> 6. Opening issues and delegating documentation work to the community.
>
> *What benefits could we have from this Informal Maintainers Team?*
>
> - Documentation will be community-driven.
> - Less reliance on a couple of individuals.
> - Transparency of work.
> - Consistency in the documentation.
> - Documentation becomes self-sustaining.
>
> *Possible Case*
>
> 1. PR with documentation changes
> 1.1 Engineers should review and make sure all code changes are valid.
> 1.2 Notify Docs Maintainers by adding a label to that PR/Issue, like
> "request-doc-maintainers". E.g.,
> https://github.com/apache/apisix-website/labels/request-doc-maintainers
> 1.3 If this PR's documentation changes meet needs (goal and guide), doc
> maintainers should approve.
> 1.4 We need at least two approval from maintainers to merge PR.
> 1.5 (Conditional) If this PR only contains English changes, Maintainers
> should submit a new PR to sync changes to Chinese.
>
> *Recommend Maintainers*
>
> Based on my observations in the community across multiple repositories, I
> recommend that we could contact these contributors when you have
> documentation needs:
>
> 1. English
> 1.1 Navendu[3]
> 1.2 Avinal[4]
>
> 2. Chinese
> 2.1 Fei Han[5]
> 2.2 SylviaBABY[6]
>
> *NOTE*
> 1. This program welcomes everyone involved, not limited to the maintainers
> listed above. Just watch the repository, find doc-related PR/Issue and join
> in. I will continue to observe the documentation contributors.
> 2. I was hoping to talk about Usecases, Tutorials, and Katacoda things, and
> now I think it's better to achieve the agreement on the current proposal
> first.
>
> What's your opinion about the Goal and this Program?
>
> [1] https://github.com/apache/?q=apisix-&type=all&language=&sort=
> [2] https://apisix.apache.org/docs/general/documentation-style-guide
> [3] https://github.com/apache/apisix/commits?author=navendu-pottekkat
> [4] https://github.com/apache/apisix/pull/6610
> [5] https://github.com/apache/apisix/pulls/hf400159
> [6] https://github.com/apache/apisix/pull/6974
>
> Best Regards!
> @ Zhiyuan Ju <https://github.com/juzhiyuan>
>
-- 
Best Regards
Ayush Das
https://github.com/iamayushdas