Add June 2025 meeting notes (#158)

Co-authored-by: Stan Ulbrych <[email protected]>

Author: hugovk

.codespellrc

@@ -1,2 +1,2 @@
 [codespell]
-ignore-words-list = Ege, Ned
+ignore-words-list = co-ordinate, Ege, Ned

docs/monthly-meeting/2025-06.md

@@ -0,0 +1,230 @@
+# Documentation Community Team Meeting (June 3, 2025)
+
+## Roll call
+
+(Name / `@GitHubUsername` _[/ Discord, if different]_)
+
+- Adam Turner / `@AA-Turner`
+- Bartosz / `@bswck`
+- Blaise Pabon / `@blaisep` / `controlpl4n3`
+- Carol Willing / `@willingc`
+- Ee / `@EWDurbin` / `@ee.durbin`
+- Jeff Jacobson / `@jwjacobson`
+- Joe Kaufeld / `@itsthejoker`
+- Kattni
+- Keith / `@KeithTheEE`
+- Lufti Zuchri
+- Ned Batchelder / `@nedbat`
+- Panagiotis Skias
+- Petr Viktorin / `@encukou`
+- Trey Hunner / `@treyhunner`
+
+## Introductions
+
+> If there are any new people, we should do a round of introductions.
+
+Several new attendees were present, a round of introductions were made.
+
+## Discussion
+
+### Translation
+
+[Carol]:
+
+> There's been lots of activity over the past 2 months about translations. It's great
+> that we have strong interest in translation. 🎉
+>
+> Building on the helpful work of Julien Palard and others on
+> [PEP 545](https://peps.python.org/pep-0545/) eight years ago and stewarding
+> translations since then, we discussed briefly at the CPython Language Summit to
+> revisit any process modifications that may be beneficial moving forward. One of the
+> key process changes that the core team found beneficial (some languages are already
+> doing) was to expand the coordinator role from an individual to more than one
+> individual when there is interest.
+>
+> Here's a [baseline doc](https://hackmd.io/@willingcn/Synk3LXWgl) to bootstrap
+> discussion at the meeting.
+
+Multiple coordinators for each translation are preferred. PEP 545 specifies one. Anybody
+who's blocked on translation should get the right tools and get the ability to do the
+translations. Carol's recommendation: put amending PEP 545 on hold & let the process
+settle down. If anyone would like to co-ordinate, file an issue and possibly let people
+know on Discourse or Discord.
+
+Is anyone blocked for translations? -- no one speaks up
+
+Questions about the document & plans? -- no one speaks up
+
+[Adam]: On the process point: if new translators should open issues, are we seeking the
+Editorial Board (EB) members to approve, and how do we have appropriate permissions
+assigned?
+
+[Carol]: My thinking is that the process should be reflected in the devguide. In pep
+545, in about three months from now, we'll amend whatever we need to, but the process
+itself tends to be better captured in the devguide instructions. Things like 'who would
+the repo belong to' and such. Right now, I can open a PR that is a recap of the meeting,
+for coordinators, if you're interested, let people know in the devguide and let the EB
+know by making a PR and making a post on Discourse under the Documentation topic that
+it's what you're interested in doing. From there, I think you guys are going to have to
+help me understand exactly what people need. Normally we message Ee or someone similar
+to help people get the right permissions. Does that address it?
+
+[Adam]: I think the only issue we really had was with the Bengali translation, but I
+think we're basically good to go otherwise.
+
+[Jeff]: spoke with Irvan Putra interested in Indonesian translation, has a
+[pull request (python/devguide#1567)](https://github.com/python/devguide/pull/1567) open
+and raised a question about removing a coordinator. Is it necessary to define a
+procedure for someone to stop being a coordinator?
+
+[Carol]: I think that if someone doesn't want to be a coordinator anymore, they should
+make a PR removing themselves from the group of coordinators and let everyone know that
+it's something they're no longer interested in. The goal of a coordinator is to create
+documentation in a target language, not to give you specific authority. If there are
+conflicts, as there sometimes are, we'll work through them, and we'll continue on. If
+anyone has any specific things that they'd like to see in the Dev Guide, @ mention me
+[Carol] and we'll take a look.
+
+[Petr]: Over the years, since seeing [PEP 1](https://peps.python.org/pep-0001/), I've
+learned the rules for submitting a successful PEP, but we are lacking a formal document
+on exactly how to submit and a PEP approved by the EB.
+
+[Adam]: It might be useful to add an explicit "what's this document meant to achieve"
+section to the PEP. Carol said: we want translations to happen, we don't want process to
+happen. Rules are important because they guide, but we need to keep in mind their
+rigidity.
+
+### Backporting large changes to 3.13
+
+[Petr]: This is a bit like pushing directly to production. Should we change the policy,
+so we keep large non-fix docs changes in pre-release branches? I wonder if it would be
+prudent to limit how we release these large blocks, as there's not enough time to debug
+if there are issues.
+
+[Carol]: Are we only talking about large document fixes, or only backporting one or two
+releases?
+
+[Petr]: Yes. If you restructure the text, add some new sections, or something similar.
+
+[Carol]: Is it related to page structure, content, or both?
+
+[Petr]: Content as well.
+
+[Adam]: To take the contrary opinion, I think the view I've always taken for docs
+changes is if it is, say, rewording a note or rewording something to make it more
+readable, as long as everything in that change still exists in the backport versions, an
+improvement is an improvement. The analytics show that a lot more people use /3 and the
+default version of the docs than specifically picking a version. If we've made a quality
+of life improvement, we should be trying to put that in front of people as quickly as
+reasonably possible. In general, better to get things out faster as long as they improve
+the experience. Delaying backporting structural changes may make it harder to edit
+later.
+
+[Ned]: I agree with Adam that there's not much harm in backporting docs changes. Even
+though Petr compared it to pushing directly to prod, I think it's not quite the same
+because we shouldn't compare code and docs. We want to make sure that we don't impact
+the drift between differences too much.
+
+[Petr]: If you fix a typo or reword a sentence, all of the translations are immediately
+null and void. They will then revert to English, and that's something that we need to
+keep in mind as well.
+
+[Carol]: Yes, yes. I think we should put in the devguide that if there's a large docs
+PR, please take into consideration prior to backporting what the translation impact
+might be and on the backported versions. Overall, I think you seem to be in agreement.
+The last thing we want to do is mess up the translations, so I think that continuing to
+discuss is a good idea. I will leave it in your capable hands, Petr.
+
+### Other topics
+
+- [Ee]: Want to discuss future of docsbuild infrastructure!
+
+We're moving more and more PSF infra to Kubernetes. We'll need the doc build server to
+move as well, and it looks like it'll be more work than a simple Django app. What amount
+of pain is there around the docs builds?
+
+The existing docs build scripts do provide an interesting interface. As long as the
+scripts are doing what the maintainers want, parallelizing them should be an easy task.
+In some future, a push could trigger build tasks that build docs which are pushed to
+object storage. [...]
+
+What's the need? What can we do in the short term? What's the long term plan?
+
+[Blaise] I'm familiar with the build process for Read the Docs, but this is different?
+
+[Ee]: Yes, the system runs on cron and ad-hoc jobs. The scripts are in
+[python/docsbuild-scripts](https://github.com/python/docsbuild-scripts)
+
+[Adam]: Performance has significantly improved. We do less now: we used to build HTML,
+E-pub, Latex[A4], Latex[letter], texinfo etc across versions and translations. Now we
+run 3 streams: all translations (round trip every 24 hours), non-HTML English (2× a
+day), HTML English (every ~30min). Would be very receptive to moving to a push-based
+approach. Currently it's just about fast enough that docs are done when CI is finished.
+People who have access: release managers, Adam, Julien. Fairly small number of people
+who would need to change their workflows. I have no experience with Kubernetes, but
+would absolutely love to go to a multicore [scalable?] system.
+
+[Ee]: Familiar enough with docs builds from supporting it for years. Ultimately, the
+output is a directory of files. We should be able to treat that as an interface. You
+tell a service what to invoke, and [...] what to serve. We'd need to find someone to
+help build out the infrastructure -- react to pushes, start the scripts, collect output.
+
+[Adam]: There are some manual tasks -- a version going end-of-life, adding switchers to
+old versions.
+
+[Petr]: Read the Docs? How far along are we in that migration?
+
+[Adam]: I did go through and get a list of issues re: how our model differs from RtD
+expectations, I might have another go at figuring out how to reconcile the approaches.
+
+[Carol]: We need to involve the relevant people - Manuel, Adam, Petr, release managers,
+etc.
+
+### A tutorial aimed at beginners to _programming_ and Python?
+
+[Joe] Wrote a lot of docs like that in bootcamps and various education. People new to
+programming have various expectations. Do we want to start with how programmers think?
+How to define a variable? 2+2=4?
+
+[Carol]: I have some thoughts, but I'd like to hear from more people who have done this
+before.
+
+[Trey]: Get people into it, then explain things as you get to them.
+
+[Kattni]: From my experience, the big problem was that it was written for people who are
+already programmers. The tutorial needs to be constructed in a manner that people want
+to do it. If it's not catchy to a beginner, people won't want to do it. That needs to
+speak to where we start and how we move through the tutorial. My experience is not
+making it through the tutorial; I added a note that it's not for programmer beginners.
+We have a lot of beginner tutorials on the net, but I went to the official one. I think
+we need to provide something on python.org.
+
+[Keith]: The outreach WG is interested [...] When I've tried to teach friends
+programming, they didn't want to learn programming, they wanted to solve a problem.
+Thinking about small projects that have a quick loop from a skeleton to a complete
+project. Those can all funnel to the existing tutorial. To answer "who is the audience":
+you have "bubbles" of interests that all funnel to a standardized tutorial that Kattni
+was envisioning.
+
+[Carol]: I'll talk about it as pathways to Python rather than a beginner tutorial. When
+I was helping people fabricate ideas (including with code), I saw people who could code
+but did not see themselves as coding. I told them how they can do something interesting
+in five lines of Python or less. When I try to do something I approach it through music.
+There's no one size fits all, it's how you apply your skills. The current tutorial
+serves people who are already developers. There's a need to democratize pathways to
+computational thinking. The core team probably isn't the right team to drive this.
+
+[Ned]: I like hearing all the ideas about how this could be approach. Not sure how to
+form a group that could move in one direction.
+
+[Trey]: I like the radical approach, but I'm afraid that it might end up as a "very big
+thing" that would hold us back. Maybe the tutorial should be "the second-best tutorial"
+for everyone.
+
+[Bartos]: The general point is that Python has a lot of different use cases and
+audiences. Everyone has different backgrounds and interests. I'd like a tutorial to be
+at the intersection at all these paths. Maybe we shouldn't answer all questions for all
+the paths. I like Raymond's talk about chunking and aliasing.
+
+[Adam]: Think about adding a list of tutorials to the index. Make it easier to jump
+around. Think about Diátaxis. We should cover `match`, not necessarily data science.

docs/monthly-meeting/index.rst

@@ -22,3 +22,4 @@ Monthly reports in chronological order.
    Mar 2025 <2025-03.md>
    Apr 2025 <2025-04.md>
    May 2025 <2025-05.md>
+   Jun 2025 <2025-06.md>