OK. We partially agree.
I have a modest understanding of the plugin api, enough to build a basic plugin. I noticed things about the api which felt lacking and that’s why I made some suggestions. But they may be the ill-advised suggestions of one who does not understand the right way of doing things. Other developers may have their own, perhaps, subpar ways of doing things.
To me it doesn’t matter whether the developer’s manual is a new site, a separate guide, or grafted into the existing api site.
If by “PR” you mean pull request I’m not sure who these pull requesters will be if not the team or individual who designed the api. I think it falls to the mind of the designer(s) to provide the why behind their design choices. The developer’s manual (e.g. updates to the blob) should not be made by just “any other developer.”