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 <juzhiy...@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>
>

Reply via email to