Documentation Community Team Meeting (January 7, 2025)

Roll call

(Name / @GitHubUsername [/ Discord, if different])

  • Adam Turner / @AA-Turner

  • Hugo van Kemenade / @hugovk

  • Petr Viktorin / @encukou

  • Trey Hunner / @treyhunner

  • Keith / @KeithTheEE

  • Ryan Duve / @ryan-duve

  • Sherry

  • Blaise / @blaisep

  • Stan Ulbrych / @StanFromIreland

Introductions

If there are any new people, we should do a round of introductions.

This was Sherry’s first meeting, introductions were made.

Reports and celebrations

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.

  • 🇵🇱 “Witamy! To jest oficjalna dokumentacja Pythona 3.13.1.” The Python docs are now officially available in Polish! 🚀 docs.python.org/pl/3/

Discussion

Translations

  • Should we change the translation progress limit for being included in the language switcher?

    • This is currently the tutorial and the bugs and functions pages.

    • Brief discussion on this threshold, no strong desire to change.

  • [Adam] Introduce a page for translation progress, like React’s, it just needs to be wired up.

    • There’s already Maciej’s page

    • Issue created: docs-community#143

    • Action: link Maciej’s page from the devguide.

    • Action: Add links to contribute.

    • Action: Look to move to https://docs.python.org/translations (via docsbuild-scripts)?

  • [Adam] Fate of the language switcher?

    • Not very maintainable or good for accessibility. It might be better to have a page for choosing languages.

    • Other docs are fairly evenly split between a page to choose and a language switcher per page.

    • Switching to the current page in another language might be important.

    • Seek feedback from those that use the switcher or frequently read non-English documentation.

Grammar documentation & Sphinx directives

  • Petr and Blaise have been working on an improved version of Sphinx’s production-list directive to represent and document Python’s grammar.

  • Petr provided a demonstration of his work.

  • There is an initial PR to add the directives at python/cpython#127835

  • This initially adds the directive, grammar snippets (and the surrounding prose) will be converted later, potentially looking to make this automatic.

Tutorial for beginners

  • Can we break up the work so people can contribute in parallel?

  • Is this better on docs.python.org, or third parties (O’Reilly, w3schools, etc.)?

    • Probably better started as a third-party effort, so you don’t need approvals up-front. (That’s also how additions to stdlib should work. Or the translation status page.)

    • Third parties know their audience better, and can serve more diverse audiences.

    • Tutorials need to cater to many different audiences (children in schools, scientists in labs, experienced programmers from other languages, those entirely new to programming), this might be better accomplished by third parties.

  • Many people start with the python.org tutorial, and some “bounce off” and go to another tutorial or leave Python entirely.

    • The existing tutorial is targeted at experienced programmers.

    • Link to other tutorials (without endorsing)?

  • Mariatta was driving the effort.