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>
