Chever-John commented on pull request #6415: URL: https://github.com/apache/apisix/pull/6415#issuecomment-1050555213
> While it makes sense to "factor" common documentation snippets when you're a developer, I think it has a negative impact on the user-experience: people will need to navigate between 2 pages to have a global overview of a plugin configuration. > > It stands to reason to have the reference documentation of a specific plugin "self-contained". > > **Alternatives:** > > 1. Keep as it is. Pro: less maintenance effort, con: degraded developer experience > 2. Duplicate common parameters in each plugin manually. Pro: good DX. Con: risk of mismatch > 3. Duplicate common parameters in each plugin in an automated way. Markdown doesn't do it natively, we will probably need some scripts. On the other hand, [AsciiDoctor](https://asciidoctor.org/) does, but we will have to migrate the whole documentation. Thanks for your comment! It helps me a lot! My solution is to make a transition by adding a short explanation of the 'batch processor' in a single file that uses the 'batch processor'. You can see it [here](https://github.com/apache/apisix/pull/6415/commits/869b87defed2fc7c042d4b70d9c97c58c66819e6). -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
