Documentation Community Team Meeting (September 2, 2025)¶
Roll call¶
(Name / @GitHubUsername [/ Discord, if different])
Ryan Duve /
@ryan-duveHugo van Kemenade /
@hugovkCarol Willing /
@willingcAdam Turner /
@AA-TurnerLufti Zuchri
Irvan Putra /
@irvan-putra/irvan.putraJacob Coffee /
@JacobCoffeeStan Ulbrych /
@StanFromIreland
Discussion¶
[Hugo] What’s the latest on the language mix-up? Do we know any translations that still have the wrong language? Are there remaining languages that need updating and CI unpausing?
[Adam] At least Japanese not yet unpaused. No update on python-docs-translations/transifex-automations#155.
[Hugo] Let’s follow up on Discord.
[Carol] Let’s have an hour session at the core sprint in two weeks so we all understand the workflow.
[Petr] Paid Transifex plan for translations: python/steering-council#297
[Hugo] Transifex is approved for one year. How can we evaluate its use towards the end of the year?
[Hugo] Pycon Greece had a good talk. Not using any web tools. Teaching people how to use Git/GitHub and get involved in open source. Spanish is similar.
Action: Hugo to share link
[Adam] Also evaluated Weblate, it was around 5% less, but would involve migrating all translations to a new platform, with added social cost.
[Carol] Suggests that by the end of the year evaluate CIs, and by PyCon US evaluate if there are improvements for users, are they finding value, and in what. Compare paid vs. unpaid. Gives us another quarter to evaluate whether to go back to unpaid.
[Adam] Yes, each team has been working independently. There are benefits of translating with similar tools and tech, for reducing workload and sharing things. For teams that are currently using Transifex, hope we can evaluate and see if we can bring in other teams to see if Transifex helps them.
[Carol] Lysandros from the Greek team spoke at the last Language Summit about it and how to come up with best practices.
[Adam] Stan’s recent split in the devguide really helped.
[Indonesian docs coordinators] We’re trying to work out how to add a workflow to support contributions via both Transifex and GitHub. Have any other communities done this, or does it tend to be an all or nothing approach with Transifex?
[Stan] This has not been done yet, successfully.
[Lufti] Cannot sync two ways. What’s the best practice?
[Stan] No existing solution - will need to set up a workflow, but could cause problems.
[Lufti] Not mandatory, so can do own thing for now.
[Stan] Transifex documentation describes commands for pushing translations
[Irvan] When adding new translators, 50% like to use GitHub, and 50% like to use Transifex. Those using Transifex are not communicating with others. User experience at Transifex is not that good, but still looking to use. Haven’t decided which approach yet. The diff conflicts if people modify the same file in different places.
[Stan] To contact translators on Transifex, you can use the built-in forum
[Hugo] Recommends using just GitHub or Transifex. Recommends coordinators decide which works best for them, can include the translation team, but coordinators decide. Then they communicate it to the team. Find a way of communicating that works, maybe the forum Stan mentions, or mailing list, or Discord, or whatever. We can create a dedicated channel if needed.
[Irvan] Someone just joined Transifex and contributed, we don’t know who they are.
[Stan] This is also a benefit of Transifex, it advertises the project for us. There are many people who translate open source projects on the platform.
[Hugo] Removing non-HTML (PDF, EPUB, etc) documentation downloads
120 voters:
Option
Percentage
I don’t care / I only use HTML / show results
47%
Remove all non-HTML downloads
36%
Keep the status quo (HTML, PDF, EPUB, and so on)
12%
Remove PDF downloads
5%
I don’t read/use Python’s documentation
0%
If we bucket the top result as happy to remove any non-HTML (because there’s a separate button to show results):
Option
Percentage
Remove all non-HTML downloads
87%
Remove PDF downloads
52%
Keep the status quo (HTML, PDF, EPUB, and so on)
12%
[Adam] Thinks we should discount the 47%. Reticent to entirely remove PDF because there have been notionally valid use cases, although skeptical of some — some said the PDF is a single file, but it’s not. Don’t want to remove and cause unnecessary harm. By far PDF is the biggest drain. The other one is for emacs. From a resource perspective, I would like to remove them. But I am in two minds. Releases also include these docs. Find most docs bugs normal build, don’t want to run into those on release day.
[Carol] Could see PDF or EPUB being useful in certain circumstances. Is it ok just to build it when something is released? To not do backports on them? In the science world, many have been dropping PDFs as they are time-consuming and a pain. For the dev branch, maybe build nightly or what the Release Manager thinks is most useful.
[Adam] Now built three times per month. PDF and EPUB are kind of similar, EPUB is much simpler, it is a load of XHTML in a zip, and takes like two mins. PDF is hours for latex stuff. Potentially drop it, and 3.15 or 3.16 will have no PDFs, and we can see if people complain. If genuinely useful in places with worse internet, don’t want to force people to create environments for PDF generation — it’s not easy.
[Adam] Suggestion: for beta, turn off PDF for what will become 3.16. If we are to announce now, that’s at least six months of lead time. Don’t know if we are overthinking the fallout of doing it. Discourse/poll is populated by very online people and is not going to capture real users.
ACTION: hook up Plausible to downloads
[Jacob] Docs nightly load avg has started causing outages ~nightly around 01:00CST (~0500, 0600 UTC). Would like to work with someone to remediate. Shared in Datadog with those that had accounts available (Adam, Hugo, Carol). Started on Aug. 5th, continues sporadically (sometimes every 2 days, sometimes 9 days.)
ACTION: Hugo+Adam to help
[Adam] discussion about splitting pages. Any opposition to just starting with simpler, standalone sections? Had a start a couple of times, never gotten to the PR stage.
[Carol] Do we have a list of target pages?
[Adam] Going by longest pages. Start with stdtypes and functions. For example, could move all the string methods to their own page.
[Adam] Long ones: datamodel, typing, logging cookbook, and so on.
[Carol] Maybe logging cookbook could be a good start?