diff --git a/.codespellrc b/.codespellrc index 4680d04..9f6e4e1 100644 --- a/.codespellrc +++ b/.codespellrc @@ -1,2 +1,2 @@ [codespell] -ignore-words-list = Ege, Ned +ignore-words-list = co-ordinate, Ege, Ned diff --git a/docs/monthly-meeting/2025-06.md b/docs/monthly-meeting/2025-06.md new file mode 100644 index 0000000..e05d42c --- /dev/null +++ b/docs/monthly-meeting/2025-06.md @@ -0,0 +1,230 @@ +# Documentation Community Team Meeting (May 6, 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. diff --git a/docs/monthly-meeting/index.rst b/docs/monthly-meeting/index.rst index b21fe42..88e0bc9 100644 --- a/docs/monthly-meeting/index.rst +++ b/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>