From aca20600eac82a5a852d8e734d5ff9b0e44dba62 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 18 Aug 2025 11:30:35 +0300 Subject: [PATCH 1/3] Add August 2025 meeting notes --- docs/monthly-meeting/2025-08.md | 112 ++++++++++++++++++++++++++++++++ docs/monthly-meeting/index.rst | 1 + 2 files changed, 113 insertions(+) create mode 100644 docs/monthly-meeting/2025-08.md diff --git a/docs/monthly-meeting/2025-08.md b/docs/monthly-meeting/2025-08.md new file mode 100644 index 0000000..527a0cc --- /dev/null +++ b/docs/monthly-meeting/2025-08.md @@ -0,0 +1,112 @@ +# Documentation Community Team Meeting (August 5, 2025) + +## Roll call + +(Name / `@GitHubUsername` _[/ Discord, if different]_) + +- Hugo van Kemenade / `@hugovk` +- Ryan Duve / `@ryan-duve` +- Petr Viktorin / `@encukou` +- Daniele Procida / `@evildmp` +- Keith / `@KeithTheEE` +- Adam Turner / `@AA-Turner` +- Trey Hunner / `@treyhunner` +- Blaise +- Ned Batchelder / `@nedbat` + +## Reports and celebrations + +> 60 second updates on things you have been up to, questions you have, or developments +> you think people should know about. Please add yourself, and if you do not have an +> update to share, you can pass. + +> This is a place to make announcements (without a need for discussion). This is also a +> great place to give shout-outs to contributors! We'll read through these at the +> beginning of the meeting. + +- July follow-ups: + - [python/cpython#137131](https://github.com/python/cpython/pull/137131) (_Link to + plaintext for "show source" links_, by Ryan Duve) + - [python/cpython#136246](https://github.com/python/cpython/pull/136246) (_Docs: a + start on an 'improve this page' feature_, by Ned Batchelder) + - t-string documentation: + [`string.templatelib` — Support for template string literals](https://docs.python.org/dev/library/string.templatelib.html), + [template string literal syntax](https://docs.python.org/dev/reference/lexical_analysis.html#t-strings) +- EuroPython documentation sprints were a success: many new contributors and many new + PRs +- PyCon UK sprints + - Daniele, Hugo, Adam hope to be there +- Hugo: We'll alternate meeting times each month to better accommodate people in + different time zones: even months at the "old" later time, and odd months three hours + earlier. Let's keep the DST adjustment as before, and try this out until the end of + the year to see how it goes. + +## Discussion + +- [Trey] Future topic: merge documentation earlier, at the same time or before code? +- Hugo: Sebastián Ramírez suggested Documentation Driven Development. + +### Topic + +- [Ellipsis documentation](https://discuss.python.org/t/99481) + + - Should we keep it short and technical (Ellipsis is just an object), or should it + explain how people use it and give examples? + + - Trey: The documentation should ideally give examples of usage. But not too much + elaboration. + - Ned: Use in place of `pass` -- we could just use '17' + - Daniele: didn't realise that `...` was an object; had always seen it as English + prose. + - Ned/Trey: the three dots are used for lots of things! We could mention that '...' is + used for many things, for example, also in doctest, recursive object + representations, and so on. + - Adam/Ned: Come up with a rubric that can guide us in future topics, rather than + specifically about Ellipsis. + - Trey: idioms & colloquialisms are more missing than he'd like, for example, dunder + not much use. + - Hugo: We recently added ~~'Walrus'~~ 'f-string'! + - Petr: Note that 'idioms' aren't dictated by the language + - see this note on `_` for prior art: + https://docs.python.org/3/reference/lexical_analysis.html#reserved-classes-of-identifiers + +- Traffic and AI search behaviour - follow up on + [Discord discussion](https://discord.com/channels/935215565872693329/1009192183137566874/1390065560091496499): + is there evidence that search engines' AI summaries are intercepting users that would + otherwise reach the documentation? + + - Seeing a collapse in traffic to technical content. + - https://analytics.python.org/docs.python.org?period=all&keybindHint=A + - Ned: Frequently asks Claude instead of using documentation + - Used when unclear what the solution is / what documentation to use + - Skipping the search engine entirely + - Daniele: Does this matter? Should we care? Ned: If it did, what would we do? We're + not going to take down docs.python.org + - Daniele: If people aren't even going to docs.python.org, they don't realise who is + behind the software/documentation. Impact on resourcing for PSF? Like turning on the + tap, you don't consider where water comes from. + - Improving documentation might improve LLM results? + - Do LLMs 'prefer' docs.python.org? + - Keith: In time, will we see greater use of documentation as more people will be + building things that are too complex for LLMs? + +- Support for non-HTML formats: _Should we bother?_. + + - Adam: Builds for PDF/LaTeX/EPUB/Text/Texinfo were unintentionally not working for + all of May-July. We had minimal complaints, is it worth keeping these formats? + - Hugo: Some complaints re: EPUB + - Adam: Perhaps we could just drop PDF? It takes the vast majority of the resources. + +- Transifex mis-propagation -- review / lessons learnt. + - we have a suite of software to sync translations, which had a bad bug. The people + who know more are not at the meeting. +- Splitting stdtypes, functions, and so on. + - they're currently big monoliths. Should we consider splitting them? How do we split + them? One page per type? One page per group of methods? + - The current state hurts SEO; splitting might hurt Ctrl+F. + - We need some sort of plan/information architecture. +- Concurrency HOWTO ([Eric's PR](https://github.com/python/cpython/pull/123163)) + + - Trey: excited to see PR. + +- Next month's meeting: 3 hours earlier, at 16:00 UTC. diff --git a/docs/monthly-meeting/index.rst b/docs/monthly-meeting/index.rst index b1d2b7d..e01572c 100644 --- a/docs/monthly-meeting/index.rst +++ b/docs/monthly-meeting/index.rst @@ -24,3 +24,4 @@ Monthly reports in chronological order. May 2025 <2025-05.md> Jun 2025 <2025-06.md> Jul 2025 <2025-07.md> + Aug 2025 <2025-08.md> From 57e4d31a14e1657992631df40a96e530fae02871 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Mon, 18 Aug 2025 11:33:49 +0300 Subject: [PATCH 2/3] Remove broken anchor --- docs/monthly-meeting/2023-09.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/monthly-meeting/2023-09.md b/docs/monthly-meeting/2023-09.md index 146dd5b..c7ee368 100644 --- a/docs/monthly-meeting/2023-09.md +++ b/docs/monthly-meeting/2023-09.md @@ -73,7 +73,7 @@ - Issues with the [current tool](https://github.com/JulienPalard/python-docs-cookiecutter): - Unmaintained / inactive - Uses third-party modules - - Next steps: Add a link from the [devguide](https://devguide.python.org/documentation/translating/#starting-a-new-translation) to this [repository](https://github.com/egeakman/python-docs-bootstrapper) + - Next steps: Add a link from the [devguide](https://devguide.python.org/documentation/translating/) to this [repository](https://github.com/egeakman/python-docs-bootstrapper) - [CAM] Quick update on reStructured Data - Summary From 320c31461337bdd164ffc2a7e7f36c3f088deffe Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 19 Aug 2025 09:06:00 +0300 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- docs/monthly-meeting/2025-08.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/monthly-meeting/2025-08.md b/docs/monthly-meeting/2025-08.md index 527a0cc..9d50d1b 100644 --- a/docs/monthly-meeting/2025-08.md +++ b/docs/monthly-meeting/2025-08.md @@ -8,10 +8,10 @@ - Ryan Duve / `@ryan-duve` - Petr Viktorin / `@encukou` - Daniele Procida / `@evildmp` -- Keith / `@KeithTheEE` +- Keith Murray / `@KeithTheEE` - Adam Turner / `@AA-Turner` - Trey Hunner / `@treyhunner` -- Blaise +- Blaise Pabon / `@blaisep` / `@controlpl4n3` - Ned Batchelder / `@nedbat` ## Reports and celebrations @@ -35,7 +35,7 @@ - EuroPython documentation sprints were a success: many new contributors and many new PRs - PyCon UK sprints - - Daniele, Hugo, Adam hope to be there + - Daniele, Hugo, and Adam hope to be there - Hugo: We'll alternate meeting times each month to better accommodate people in different time zones: even months at the "old" later time, and odd months three hours earlier. Let's keep the DST adjustment as before, and try this out until the end of @@ -68,7 +68,7 @@ - Hugo: We recently added ~~'Walrus'~~ 'f-string'! - Petr: Note that 'idioms' aren't dictated by the language - see this note on `_` for prior art: - https://docs.python.org/3/reference/lexical_analysis.html#reserved-classes-of-identifiers + - Traffic and AI search behaviour - follow up on [Discord discussion](https://discord.com/channels/935215565872693329/1009192183137566874/1390065560091496499): @@ -76,7 +76,7 @@ otherwise reach the documentation? - Seeing a collapse in traffic to technical content. - - https://analytics.python.org/docs.python.org?period=all&keybindHint=A + - - Ned: Frequently asks Claude instead of using documentation - Used when unclear what the solution is / what documentation to use - Skipping the search engine entirely @@ -96,6 +96,7 @@ all of May-July. We had minimal complaints, is it worth keeping these formats? - Hugo: Some complaints re: EPUB - Adam: Perhaps we could just drop PDF? It takes the vast majority of the resources. + - Followup: - Transifex mis-propagation -- review / lessons learnt. - we have a suite of software to sync translations, which had a bad bug. The people