|
| 1 | +# Documentation Community Team Meeting (July 1, 2025) |
| 2 | + |
| 3 | +## Roll call |
| 4 | + |
| 5 | +(Name / `@GitHubUsername` _[/ Discord, if different]_) |
| 6 | + |
| 7 | +- Adam Turner / `@AA-Turner` |
| 8 | +- Hugo van Kemenade / `@hugovk` |
| 9 | +- irvan.putra |
| 10 | +- kattni |
| 11 | +- Keith / `@KeithTheEE` |
| 12 | +- Lutfi Zuchri |
| 13 | +- maciek |
| 14 | +- mattwang44 |
| 15 | +- Ryan Duve / `@ryan-duve` |
| 16 | + |
| 17 | +## Introductions |
| 18 | + |
| 19 | +> If there are any new people, we should do a round of introductions. |
| 20 | +
|
| 21 | +Several new attendees were present, a round of introductions were made. |
| 22 | + |
| 23 | +## Discussion |
| 24 | + |
| 25 | +### Topic |
| 26 | + |
| 27 | +- [Ryan] Has there been prior work to automatically detect which Python functions exist |
| 28 | + but aren't in the documentation? I'm imagining something like |
| 29 | + [Moto's implementation coverage document](https://github.com/getmoto/moto/blob/master/IMPLEMENTATION_COVERAGE.md) |
| 30 | + for Boto3, but for documentation coverage. This popped up after |
| 31 | + [seeing a PR](https://github.com/python/cpython/pull/136024) to add documentation for |
| 32 | + a missing function in `importlib.metadata`. |
| 33 | + |
| 34 | + - Adam: this seems valuable, but not done before. Previously, we had talked about the |
| 35 | + calendar module where we have intentionally non-documented features. It'd be good to |
| 36 | + add the breakdown a dimension that indicates whether a function is intentionally not |
| 37 | + documented or not. Additionally, an existing coverage tool (for example, |
| 38 | + `sphinx.ext.coverage`) could be modified to come up with this list. |
| 39 | + |
| 40 | + - Could be used as a central store of what is missing, what is intentionally missing, |
| 41 | + perhaps a good 'place to get started' for newer contributors. |
| 42 | + |
| 43 | + - Kattni: this could be valuable especially for getting new people involved and some |
| 44 | + numbers around the coverage. |
| 45 | + |
| 46 | +- [Adam] I'd like to broach the idea of jargon being used in the standard library and |
| 47 | + how to make it more effective. |
| 48 | + |
| 49 | + - [Hugo] There are times in the stdlib where it's OK to rely on jargon. |
| 50 | + |
| 51 | +- Irvan: Some jargon should be kept in English because translating it will make it |
| 52 | + harder to be understood, because then the target user will need to re-translate it to |
| 53 | + English when reading. So perhaps, having a feature that when hover cross-references to |
| 54 | + explain/disambiguate jargon? |
| 55 | + |
| 56 | +- Kattni: Recently wrote a guide on using a stdlib tool, but had to look up how to |
| 57 | + properly reference various things. Specifically, referring to a module in the standard |
| 58 | + library and initially got wording wrong. |
| 59 | + |
| 60 | +- Keith: Education & Outreach: Moving from planning to doing. Interested in resources |
| 61 | + for (1) teachers, (2) individuals new to programming, (3) improving python.org. |
| 62 | + |
| 63 | +- Adam: we are reference-docs-biased, we have a high bounce rate. |
| 64 | + |
| 65 | +- Irvan: PHP docs allow comments (user contributed notes), but I am not really sure if |
| 66 | + it is good if we follow that, so maybe we can allow that in other initiatives like the |
| 67 | + new resources for teachers/beginners. |
| 68 | + |
| 69 | +- Ned: current [Report a Bug article](https://docs.python.org/3/bugs.html) could be |
| 70 | + improved to better suggest improvements. |
| 71 | + |
| 72 | + - Show source should link to raw rst code (`?plain=1`) rather than the render. |
| 73 | + |
| 74 | +- [Ryan]: could we gather all the docs referrer headers and see whether there's info to |
| 75 | + be captured on the pages that are linking to the docs? |
0 commit comments