2023-12.md

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.