Documentation Community Team Meeting (July 1, 2025)

Roll call

(Name / @GitHubUsername [/ Discord, if different])

  • Adam Turner / @AA-Turner

  • Hugo van Kemenade / @hugovk

  • irvan.putra

  • kattni

  • Keith / @KeithTheEE

  • Lutfi Zuchri

  • maciek

  • mattwang44

  • Ryan Duve / @ryan-duve

Introductions

If there are any new people, we should do a round of introductions.

Several new attendees were present, a round of introductions were made.

Discussion

Topic

  • [Ryan] Has there been prior work to automatically detect which Python functions exist but aren’t in the documentation? I’m imagining something like Moto’s implementation coverage document for Boto3, but for documentation coverage. This popped up after seeing a PR to add documentation for a missing function in importlib.metadata.

    • Adam: this seems valuable, but not done before. Previously, we had talked about the calendar module where we have intentionally non-documented features. It’d be good to add the breakdown a dimension that indicates whether a function is intentionally not documented or not. Additionally, an existing coverage tool (for example, sphinx.ext.coverage) could be modified to come up with this list.

    • Could be used as a central store of what is missing, what is intentionally missing, perhaps a good ‘place to get started’ for newer contributors.

    • Kattni: this could be valuable especially for getting new people involved and some numbers around the coverage.

  • [Adam] I’d like to broach the idea of jargon being used in the standard library and how to make it more effective.

    • [Hugo] There are times in the stdlib where it’s OK to rely on jargon.

  • Irvan: Some jargon should be kept in English because translating it will make it harder to be understood, because then the target user will need to re-translate it to English when reading. So perhaps, having a feature that when hover cross-references to explain/disambiguate jargon?

  • Kattni: Recently wrote a guide on using a stdlib tool, but had to look up how to properly reference various things. Specifically, referring to a module in the standard library and initially got wording wrong.

  • Keith: Education & Outreach: Moving from planning to doing. Interested in resources for (1) teachers, (2) individuals new to programming, (3) improving python.org.

  • Adam: we are reference-docs-biased, we have a high bounce rate.

  • Irvan: PHP docs allow comments (user contributed notes), but I am not really sure if it is good if we follow that, so maybe we can allow that in other initiatives like the new resources for teachers/beginners.

  • Ned: current Report a Bug article could be improved to better suggest improvements.

    • Show source should link to raw rst code (?plain=1) rather than the render.

  • [Ryan]: could we gather all the docs referrer headers and see whether there’s info to be captured on the pages that are linking to the docs?