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> >