I would like to get an overview document added to the PyPA documentation, to be listed ahead of, or right beside, the Tutorial. As an outsider, the publishing flow is unclear.
Here is what I propose: css/pypa-the-missing-outline.md at pypi · cameron-simpson/css · GitHub
It has had some welcoming feedback.
This is the discussion which led me to write it: Modernising my packages - am I thinking about this all wrong? - #25 by cameron
and I’m not alone in finding the existing docs somewhat overwhelming as they stand: Where to get started with pyproject.toml? - #17 by sinoroc
There’s discussion in the “modernising my packages” thread about why I think we need a concise overview of the flow. I’ll repeat here what my design objectives for the document are:
This document is supposed to:
- be short - a layout of the flow to distribute something, describing the pieces and their relationships
not be a tutorial; there’s a nice tutorial already
- with some examples but not prescriptive except in the sense of prescribing “you need to make some distribution files”
- it has a point list of the objectives, starting at the author and arriving at the end user
- it goes over each of those points in a little detail after the main list, to make them clear
- it has some references to the places where relevant things are specified (PEPs, tools)
How can I move this forward?
I have some suggestions for the text:
Use very simple English. Avoid synonyms and any words that a beginner, non-native English speaker, or reader from different technical background might mistake for technical terminology.
Most importantly, avoid introducing even more new terminology. Python Packaging already has too many confusing concepts.
Examples: packaging flow, source tree, build artifact, upload facilities, generic wheel, package distribution service, …
They are not in the glossary. They should be added if they are important concepts. They should be replaced by simpler words if they are not important concepts.
Remove filler words like “of course” and vague words like “typically”, “usually”, “including but not limited to”. Remove any sentence, piece of information, any single word not absolutely necessary. For example the entire two first paragraphs should be removed.
Don’t mention PEPs and PEP numbers. They are change proposals, not documentation.
Add some diagrams.
The idea is good I think.
How can I move this forward?
If you’re asking about process, you should be able to create a PR against the packaging user guide here. The maintainers there can help with details of wording, style and layout.
I’d honestly suggest doing that, using your existing document as the starting point for a new bullet point under the Getting Started section, something like “To get an overview of the packaging workflow”. Improving something that’s there is easy, the key thing is to get it added.