# Documentation Community Team Meeting (May 1, 2023) ## 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](https://us.pycon.org/2023/about/keynote-speakers/#ned-batchelder) * [PyCon](https://us.pycon.org/2023/), April 19-27 2023: * CAM & Erlend's talk, "[Iteration toward Transformation of the Python Documentation](https://us.pycon.org/2023/schedule/presentation/88/)", 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. * Main benefit: multiple admins instead of single-person bottleneck with Netlify. * [python/cpython#103843](https://github.com/python/cpython/pull/103843) * GH action to update the link from the PR - we don't need one for Netlify * [JDLH thinks this means] GitHub action to update a link to a documentation preview on ReadTheDocs from the GitHub Pull Request page. We don't need such a preview for the current docs as published at Netlify. * Example of preview link: Pull Request [#104013, **gh-104010: Separate and improve docs for typing.get_origin and typing.get_args**](https://github.com/python/cpython/pull/104013), contains a link to a preview of the documentation reflecting the Pull Request's effects, at [https://cpython-previews--104013.org.readthedocs.build/en/104013/](https://cpython-previews--104013.org.readthedocs.build/en/104013/). * 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](https://python-docs-es.readthedocs.io/es/3.11/) 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](https://mermaid.js.org/) / [mermaid-cli](https://github.com/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](https://github.com/python/peps/pull/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](https://python-docs-es.readthedocs.io/es/3.11/CONTRIBUTING.html) (docs-ception) that teaches the whole process - how do we write such docs? - HackMD or Google Docs - [Python Docs Community web page](https://docs-community.readthedocs.io/en/latest/) - source: [github.com/python/docs-community](https://github.com/python/docs-community) e.g. front page source: [docs-community/docs/index.rst](https://github.com/python/docs-community/blob/main/docs/index.rst) - start having better landing page for Docs there - 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](https://docs-community.readthedocs.io/en/latest/community/contributing.html) - 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 these 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](https://github.com/python/python-docs-zh-tw/issues/399))