Python packaging documentation feedback and discussion

I think that is quite far from perfect. As I mentioned in another post, if the tabs are meant as examples, the tutorial needs to explicitly say that. Otherwise it looks like it is offering an exhaustive list of options.

Even so, I still do not see any reason to show more than one at this particular point in this particular tutorial. A tutorial on “how to package a simple Python project” does not need to show multiple backends. It should decide on the one that is best for that purpose — perhaps including simplicity, breadth of adoption, and ease of transitioning to more complicated projects — and show that one. There can be a separate tutorial about why someone might need others.

If you’re saying that you think the tutorial is fine because no one raised an issue on the issue tracker, I think that is not a justifiable conclusion. Many people may have given up. Others may have understood after spending more time than they ought to have. If we’re lucky, some asked in some external forum (like this), or even on this very website.

Now, admittedly not all of that can be traced directly to this tutorial, but there is no doubt in my mind that there is widespread sentiment that Python packaging has too many ways to do too many things and it’s hard to navigate them all. I’m sympathetic to the view that that situation is in some sense a consequence of Python’s success and the wide range of ways it’s used. But confronting users with multiple backends in a situation where they don’t need them only exacerbates the problem. In a tutorial that only needs one build backend, there is no need to say anything about any others except “click this link if you want to learn more”. There should be one and only one obvious way to do it.