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 /
@encukouDaniele Procida /
@danieleprocidaHugo van Kemenade /
@hugovkJim DeLaHunt /
@JDLHRyan Duve /
@ryan-duveNed Batchelder /
@nedbatBradley /
@shenanigansdEzio Melotti /
@ezio-melottiCAM Gerlach /
@CAM-GerlachUsman Akinyemi /
@Unique-Usman
Discussion#
[Ryan] Standard library documentation reference and adding types to it in a structured way. For example,
collections.Counter.most_commoncould 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.