Description
https://packaging.python.org/ is currently titled Python Packaging User Guide and contains both information targeted towards Python developers (tutorials, guides and discussions) as well as the specifications maintained by the PyPA targeted towards Python package tooling developers. For some topics the site has pages for both perspectives, e.g. there's the Writing your pyproject.toml
guide and the pyproject.toml specification.
I see two issues with the current setup for users: 1) it's very easy to stumble into the specification section when using the search and 2) guides and specifications visually look the same (you have to look at either the sidebar or the URL path to identify where you are).
For example, see what currently happens when a user searches for "virtual environment":
The third result here seems to be the most comprehensive since it's a page titled Python Virtual Environments
, however that link will actually take you to the Python Virtual Environments specification, which isn't really helpful for users trying to learn about virtual environments.
Even when a user guide exists, the search currently sometimes yields a wrong first result. Searching for "writing pyproject.toml" yields pyproject.toml specification as the first result and Writing your pyproject.toml only as the 3rd result.
While the latter could be fixed by prioritizing title matches, the former doesn't seem to be easily solvable with both sections living in the Sphinx site. So I think you should consider moving the PyPA specifications to a separate site (perhaps pypa.io or a different subdomain).