[GitHub] [apisix-website] yzeng25 commented on pull request #945: docs: Optimize text descriptions and keywords.

[GitBox <gi...@apache.org>]

yzeng25 commented on pull request #945:
URL: https://github.com/apache/apisix-website/pull/945#issuecomment-1060413894


   Batching all of these procedures (rename, update keywords, descriptions, add text contents) up in one pull request is not a wise decision. It creates the following problems.
   
   1. Once a file is renamed, its contents appear as all new during review. This creates trouble for reviewers. Put yourself in reviewers' shoes, how would you feel when you need to review a pull request with 215 files (the number of files in this pull request as of 17:36 GMT+8)?
   2. Many of the files are ended with time stamp `2022xxxxx` suffixes. Please fix them. 
   ![gmSowKTowJ](https://user-images.githubusercontent.com/36651058/157005561-648c792d-d2cf-4090-bb6f-5479f67ae3cd.png)
   3. Some of the files are already published on Medium[1] page, which also provides link referring back to Apache APISIX's blog[2]. Do you know changing all links could lead to reference failures as well?
   
   I would suggest break this pull request into different parts and solve them one by one.
   
   1. Identify all files that can't be renamed directly for Reason 3 stated above. It can be solved with a trick called `slug`. Update keywords, update descriptions, add text contents on them. This could be a pull request.
   2. Update keywords, update descriptions, add text contents for the rest of the files. This could be one or more pull requests, preferably submitting them by months or quarters.
   3. Rename files in Part 2. The reason to leave the renaming at the end are to ease the process of review and to avoid merge conflicts. Please think of other contributors and other pull requests hanging there as well. This could be another pull request.
   
   I know you are eager to solve this problem soon. But using brutal force to solve the problem just isn't the most effective way. Things are always more complicated than your imagination. Please think twice before you act.
   
   Please fix the lint as well, thanks!
   
   [1]https://medium.com/@ApacheAPISIX
   [2]https://apisix.apache.org/blog


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org