Since there is a discussion about adopting the Diátaxis guidelines for documenting Python, I noticed that the Packaging guide is following the same principles.
One of the recommendations for tutorials is to remove all cognitive load about options and alternatives. The idea is to get an unfamiliar reader to complete an educative project (such as build a package from some example code).
The packaging tutorial already diverges a lot from the recommendations by introducing abstract context and explanations. That’s not bad in itself (Diátaxis puts a lot of emphasis on documenting a product, while Python packaging is an ecosystem) but I find it true that the tutorial generates a lot of cognitive load.
The hardest-to-digest part is possibly “Configuring metadata”:
- it presents two alternatives, static or dynamic
- it explains each of them, and it compares them
- it recommends one of the alternatives, before even telling the reader they need to make a decision
- then it proceeds to document both alternatives (am I supposed to have made my mind up at this point, or should I read on both branches and decide later?)
- it provides what feels like a compact reference to all the configuration options
- it makes a mention of my “username” for the first time in the document, in bold characters, suggesting I’m supposed to do something important here, but giving no instructions
All of this comes immediately after the casual mention that this step might be “completely different” if I were to choose a different build system. This is enough load to freeze even experienced folks (I know I did).
My suggestion:
- Amend the tutorial to adopt PEP 621 and choose any backend. The chosen backend here is not a recommendation. It’s a tool that will unblock a learner so that they can complete the tutorial
- Mention in the tutorial that “we will use X as a build backend” when
build-systemis set. - Delegate the more ambiguous tasks to guides:
- New “How to choose a build system” guide: a decision tree mostly about PEP 517 vs legacy, setuptools vs others, and specialized builders; not a place to compare Poetry vs Flit vs Hatch vs the hottest new alternative (but it might be worth mentioning what kind of implication the choice might have)
- Refresh “Packaging and distributing projects” to specify that it’s setuptools-specific, cover everything that right now is in “Configuring metadata” in the tutorial, update for PEP 517
- Emphasize “guides” more throughout the documentation, because they have the potential to do a lot of the heavy lifting. My guess is that users come with specific tasks to accomplish, and the tutorial cannot have the burden to cover all of them.
I don’t see how backend agnosticism is a goal that supports learners. The tutorial would be worse with more branching. The intention here seems to be to avoid accidentally blessing one backend over others. If that’s the case, can it be achieved without hindering the first learning experience? Some options:
- In-line with the setting of
build-backendexplain that it’s a choice and link to a different resource (be it the “How to choose” guide I suggested above, or any discovery resource) - The same, but in a box that is obviously not part of the tutorial itself
- Emphasize the part in “Next steps” which already recommends considering alternatives, and link to a dedicated resource
- Create and maintain a new minimal backend that implements PEP 621 and can build a wheel, but will never support anything more complex than the tutorial itself. It could be a wrapper on flit_core or hatchling or equivalent, but that would not be apparent to a user.