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 trainingNed, 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.
Main benefit: multiple admins instead of single-person bottleneck with Netlify.
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, 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/.
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
source: github.com/python/docs-community e.g. front page source: docs-community/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.
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.