Documentation Community Team Meeting (May 2023)#

  • Date: 2023-05-01

  • Time: 19:00 UTC

  • This HackMD: https://hackmd.io/@encukou/pydocswg1

  • Discourse thread (for May)

  • Meeting reports (the latest one might be an unmerged PR)

  • Calendar event: (send your e-mail to Mariatta for an invitation)

  • How to participate:

    • Go to Google Meet and ask to be let in.

    • To edit notes, click the “pencil” or “split view” button on the HackMD document. You need to log in (e.g. with a GitHub account).

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!

Roll call#

(Name / @GitHubUsername)

  • Mariatta @Mariatta

  • Petr Viktorin @encukou

  • Cristián Maureira-Fredes @cmaureir

  • Hugo van Kemenade@hugovk

  • Jim DeLaHunt @JDLH

  • Ryan Duve @ryan-duve

  • Joanna Jablonski @jablonskidev

  • Ezio Melotti @ezio-melotti

  • Keto Zhang @ketozhang

  • Manuel Kaufmann @humitos

  • Ned Batchelder @nedbat

  • C.A.M. Gerlach @CAM-Gerlach

  • Marcus Sherman @betteridiot

  • Yaa Nuamah Kusi-Fordjour

Introductions#

  • Petr, Python core dev, runs these meetings

  • Mariatta, one of the people who started the Docs group. Just chaired Pycon US

  • Hugo, from Helsinki, Python core dev

  • Ryan Duve, data scientist, Python user interested helping with community docs stuff

  • Joanna, Python education

  • Jim, from Vancouver, Canada; reads docs & fixes things he notices

  • Manuel Kaufmann from Argentina now in Spain, translations, Read the Docs, CPython translation in Spanish, PSF Fellow

  • Marcus Sherman, from Portland, Maine @ Northeastern University, @betteridiot, biologist by training

  • Ned, from Boston, made the docs official, eager to see this group grow into a large & welcoming community

  • Cristián Maureira-Fredes, CPython Spanish translation

  • Keto Zhang, software engineer in astronomy, went to Cam’s talk at PyCon

  • CAM, gave the talk at PyCon, new Python core dev, from Huntsville, Alabama, Spyder maintainer, looking to be a full-time open-source dev & documentarian

  • Ezio, core Dev, working on docs and infrastructure

Reports and celebrations#

Congrats to CAM!

Congrats Ned for the keynote at PyCon US 2023

  • PyCon, April 19-27 2023:

    • CAM & Erlend’s talk, “Iteration toward Transformation of the Python Documentation”, went well, good discussions afterwards and many joined the Discord wanting to contribute

    • Sprints: some docs contributors, including people making their very first CPython contribution

    • Sprints: [Hugo] switched CPython docs previews from Netlify to RtD.

  • GH action to update the link from the PR - we don’t need one for Netlify

  • For moving main docs, a few more things are needed, but they’re tracked at the RtD side

  • We’re using a personal account (Mariatta’s). Not ideal. Right now community version of RtD doesn’t support multiple owners, there are workarounds. Organizations are only in the commercial version so far.

  • would be nice to have an ORG account.

  • curious about workflow for translations, etc how to migrate the docs translations and the multi-version support to readthedocs

    • Manuel set up python-docs-es.readthedocs.io, the Spanish translation on RtD. The source files aren’t in the translation repo, so the English version is added as a submodule. Translations need to be added as a new project, then connected in the admin interface.

    • For multiversion, the version switcher is injected on the bottom right. Each version is a branch or a tag, once enabled they get built.

    • That said, RtD is rebuilding the flyout (switcher) to make it easier to customize. Working together with Pradyun (Furo, Lutra)

  • The “this is only a preview” header is missing.

Discussion#

  • Building images with mermaid.js / mermaid-cli.

    • @tysonclugg is trying to put together docs on concurrency which would benefit from good diagrams

    • Some other tool to explore?

  • [Hugo] PEPs infra: PR opened to improve text readability / page performance: python/peps#3132

  • [Ned] Best entry point to working on docs, for people newly interested in helping?

    • we need clear onboarding

    • do we have style guide?

    • Cristian: In the python-docs-es team we have a page inside the docs (docs-ception) that teaches the whole process

    • how do we write such docs?

      • HackMD or Google Docs

    • Python Docs Community web page

    • The landing page should point to where the conversations happen, e.g. the Discourse server. For a group of translators, a Telegram group is the conversation place. A conversation place helps people support each other.

  • Docs Community Contributing Guide

  • Translation group

    • how to coordinate with the wider translations group, share tips, etc

    • Manuel: started 3 years ago: have a place to connect with other translators and resources

    • Julien introduced the tools for translation.

    • Create channel for translations

    • Cristian: It also could be a good idea to have in the main Documentation page (that we will have soon) something like “Wanna help with a translation of these docs? check out this initiatives ”

    • Ezio: I already brought it up a couple of times, but it would be good to unify the translation infrastructure and tools (see e.g. python/python-docs-zh-tw#399)

Next meeting#

The docs team generally meets on the first Monday of every month.

We have a recurring Google Calendar event for the meeting. Let Mariatta know your email address and she can invite you.