Documentation Community Team Meeting (December 5, 2023)

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 as most_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

  • devguide.python.org/getting-started/git-boot-camp/#accepting-and-merging-a-pull-request

  • python/devguide#1235

  • 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.