[GitHub] [apisix] avinal commented on issue #6461: docs: New architecture/structure for the APISIX documentation

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

avinal commented on issue #6461:
URL: https://github.com/apache/apisix/issues/6461#issuecomment-1061477443


   Hello all, Thank you all for the review. here is the update for the proposal based on your suggestions. 
   
   > Could the description of 'external plugins' more deliberated? I think there could have several documents to introduce the way to write plugins in different languages.
   
    Yeah sure, there is just one problem, since external plugins may or may not be supported by APISIX, we can only explain the preferred way to write them and not explain every possible way. It would be good to have different pages for different writing methods.
   
    
   > It depends what you mean by "little introduction". I really dislike coming to a project I don't know, and being presented with the update of the latest versions, but not understanding what it is about.
   
   Little introduction means just necessary stuff about the project, neither too deep nor too shallow. I will add some explanation. 
   Thank you for the examples, will add something similar to this doc as well.
   
   
   
   > 1. Getting Started → Contribution Guide/Community Guide: How about linking to [`https://apisix.apache.org/docs/general/contributor-guide`](https://apisix.apache.org/docs/general/contributor-guide)?
   
   Both ways are possible, either we can move the whole doc to the contributor guide section or just link it. Since the doc is already there, it would be nice to just link.
   
   > 2. Usecases/How-to Guides: Are they the same contents?
   
   There is a slight difference between these two topics. The use cases are what we intend the application to be used for. And how-to Guides are questions answered from a particular use-case perspective. In general, they mean the same. I put it there just to decide which topic to use.
   
   > 3. API → AdminAPI: Will we split different entities into different sections?
   
   If there are separable entities then it makes sense to split them into different sections. Right now the page is just too large, ideally, one page shouldn't contain more than 2000 words(excluding code), or it becomes too hard to follow and search. So splitting will be nice.
   
   > 4. Plugins → External Plugins: Just to make sure, do you mean Java/Go/xx Plugin Runner or plugins made by unofficial members? e.g [`https://github.com/swisscom/apisix-opa-plugin`](https://github.com/swisscom/apisix-opa-plugin)
   
   Yes, we can list popular external plugins and the preferred method to create them. This will expand the applications of APISIX.
   
   > 5. Plugins: Many developers report that they cannot work well with Plugin Development in different machines/environments, could we have some recommended environments? or PDK (Plugin Development Kit, @tzssangglass is familiar with this).
   
   Yes, that is why we are going to a plugin development section. And we can then suggest the best practices for plugin development.
   
   
   > We can add security, observability, Kubernetes deployment, multiple development language development plugins, WASM, etc. In the protocol part, MQTT and GraphQL are also worth mentioning. 
   
   Sure, I am not very familiar with the protocols, will add them once I have discussed them with the engineers. 
   
   
   > Would it be better to add a `Concepts` section to introduce `route` `service` `consumer` `upstream` ?
   
   Yeah, I have already added that `Definition of important keywords` inside `architectural design`, but `Concepts` seems a better choice of word, please suggest if I should move them out in a separate chapter instead.
   
   
   > Perhaps a `Plugin Development` directory is needed to collect documentation related to plugin development.
   > 
   > under `Plugin Development` maybe:
   > 
   >     1. Build development environment
   > 
   >     2. Development Process
   > 
   >     3. Development and debugging skills
   > 
   >     4. Writing test cases
   
   I have added this as `Creating custom plugins`, but `Plugin Development` seems more suitable, will rename it and add the suggested sections. 
   
   
   > Besides these aspects, I hope that the below things can be added:
   > 
   >     1. Guide about openresty/ngx_lua development (give some materials are also good);
   > 
   >     2. Not only how to write case but also how to run them;
   > 
   >     3. The Plugin Development Kit docs
   
   Seems like a great addition to me. Will add them as well.
   
   > Hi, I have a little advice here:
   > 
   >     * I think it would be a good idea to put the learning APISIX and user cases into a single place like a learning library.
   
   That would be more clear and expressive, Will restructure.
   
   > Maybe add `Best Practices` ? e.g. Different cluster size and best practices , Upgrade best practices , ide best practices(idea emmylua plugin, vscode+emmylua plugin , zbstudio ...).
   > 
   > e.g. ansible best practices https://docs.ansible.com/ansible/2.8/user_guide/playbooks_best_practices.html
   
   There was some consideration at first but haven't thought about it much. I will see them and add them. Thanks for the example.
   


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