Google Drive
Gist
Clipboard
By participating in this meeting, you are agreeing to abide by and uphold the PSF Code of Conduct. Please take a second to read through it!
Example topics for discussion:
docs.python.org, peps.python.org, devguide.python.org, etc.(Name / @GitHubUsername [/ Discord, if different])
@AA-Turner@bswck@blaisep / [controlpl4n3]@willingc@EWDurbin / @ee.durbin@jwjacobson@itsthejoker@KeithTheEE@nedbat@encukou@treyhunnerIf there are any new people, we should do a round of introductions.
Several new attendees were present, a round of introductions were made.
60 second updates on things you have been up to, questions you have, or developments you think people should know about. Please add yourself, and if you do not have an update to share, you can pass.
This is a place to make announcements (without a need for discussion). This is also a great place to give shout-outs to contributors! We'll read through these at the beginning of the meeting.
skipped; moved straight to substantive topics
[Someone, Stan is unavailable this week]
Python Translations Progress Update
| Language | 30 Days Change | Bumped to 3.14? |
|---|---|---|
| Simplified Chinese | 2.22 | ✅ |
| Brazilian Portuguese | ?.??* | ✅ |
| Spanish | 0.1 | ❌ |
| Japanese | 0.8 | ✅ |
| Ukrainian | 0.0 | ❌ |
| Korean | 4.43 | ❌ |
| Traditional Chinese | 1.32 | ❌ |
| French | 0.0 | ❌ |
| Polish | 1.11 | ✅ |
| Greek | 0.78 | ✅ |
| Turkish | 0.0 | ❌ |
| Italian | 0.0 | ❌ |
| Persian | 0.24 | ❌ |
| Romanian | 0.0 | ❌ |
| Russian | 0.19 | ✅ |
| Bengali | 0.11 | ✅ |
| Arabic | 0.0 | ❌ |
| Hindi | 0.0 | ❌ |
| Hungarian | 0.0 | ❌ |
| Indonesian | 0.0 | ✅ |
| Marathi | 0.0 | ❌ |
| Lithuanian | 0.0 | ❌ |
| Portuguese | 0.0 | ❌ |
* Current dashboard issue.
For reference, the current wordcount of the (3.14) Docs is: 1,600,561. (~100,000 more than 3.13)
Source: Generated by this script using index.json as of Jun 1, 14:08.
[Name] topic
[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 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 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 recomendation: 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 EB members to approve, and how do we have appropriate permissions assigned?
[Carol]: What my thinking is is that the process should be reflected in the dev guide. In pep 545, in about 3 months from now, we'll amend whatever we need to, but the process itself tends to be better captured in the dev guide 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 dev guide 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) 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, 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 guides, but we need to keep in mind their rigidity.
[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 dev guide 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.
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 & ad-hoc jobs. The scripts are in 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 & 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 no 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 EoL, 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.
[Joe] Wrote a lot of docs like that in bootcamps & various educatin. 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 programers. 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 thru 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 outhreach WG is interested […] When I'v 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 funnet 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 5 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 skils. 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 dirsction.
[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'ts talk about chunking and aliasing.
[Adam]: Think about adding a list of tutorials to the index. Make it easier to jump around. Think about Daiátaxis. We should cover match, not necessarily data science.
The docs team generally meets on the first Tuesday of every month around 19:00-ish UTC.
We have a recurring Google Calendar event for the meeting. Let Mariatta know your email address and she can invite you.
-
Any changes
Be notified of any changes
-
Mention me
Be notified of mention me
-
Unsubscribe
Subscribe