Documentation Community Team Meeting (December 2023)¶
Date: 2023-12-05
Time: 20:00 UTC
This HackMD: https://hackmd.io/@encukou/pydocswg1
Discourse thread (for December)
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
[/ Discord, if different])
Petr Viktorin /
@encukou
Daniele Procida /
@danieleprocida
Hugo van Kemenade /
@hugovk
Jim DeLaHunt /
@JDLH
Ryan Duve /
@ryan-duve
Ned Batchelder /
@nedbat
Bradley /
@shenanigansd
Ezio Melotti /
@ezio-melotti
CAM Gerlach /
@CAM-Gerlach
Usman Akinyemi /
@Unique-Usman
Discussion¶
[Ryan] Standard library documentation reference and adding types to it in a structured way. For example,
collections.Counter.most_common
could be written asmost_common(n: int) -> list[tuple[Any, int]]
.[Petr] … or
list[tuple[KeyType, int]]
?This has been discussed. There was opposition to adding the types to the stdlib code itself.
[Jim] I sometimes wish for more normative, less chatty module documentation:
e.g. heapq module
e.g. old issue 29428 Doctest documentation unclear about multi-line fixtures
[Petr] Use emoji to illustrate good and bad example commit messages
https://devguide.python.org/getting-started/git-boot-camp/#accepting-and-merging-a-pull-request
Should we do this for PEPs? See python/docs-community#22
[Hugo] See also python/peps#3567 for green/red sidebars for good/bad example code in PEPs
[Jim] don’t forget accessibility constraints when coming up with the style guide. For example, some readers are red/green colorblind. ✅/❌ are good in that they are legible even without color.
[Ryan] Thoughts about completing TOML->JSON conversion table and the TOML spec
Reports and celebrations¶
PEP 732 (“The Python Documentation Editorial Board”) has been submitted to the steering council python/steering-council#220
[Jim] FYI, Unicode Standard is changing form of authoritative standard documents from PDF to HTML, with corresponding change to document production tooling. If this is interesting I can provide more information. I am in the working group which is working on the new tooling.
Follow-ups from previous meeting(s)¶
[Petr] Railroad diagrams
Streams have kind of been on other topics too
[Ege/Hugo/CAM] Analytics (Plausible) - CAM sent an e-mail (around late October), no reply yet
CAM sent multiple follow-ups
Hugo sent a follow-up two weeks ago
Discussion on core dev Discord that is supportive
Still no reply… :(
Next meeting¶
The docs team generally meets on the first Tuesday of every month around 20:00-ish UTC.
[Jim] The first Tuesday of next month is 2 January. Will we be ready for this meeting on the day after New Year’s Day? Answer: Basically yes; those who are ready will show up, others won’t.
We have a recurring Google Calendar event for the meeting. Let Mariatta know your email address and she can invite you.