I echo Pablo's comment about thoughtful discourse as this is discussed.

For library maintainers that are writing APIs that involve workflows across multiple projects maintained by different people, better information and documentation is very important.

We are balancing the needs of different user groups. An all or nothing approach to documenting / and positional only arguments will not serve the different groups well. What will serve them is coming up with an approach that will work (though not perfectly) for each group. In essence, balancing and compromising are critical.

I suggested an approach earlier which I would appreciate folks give a closer look to its merit.