|
| 1 | +# Documentation Community Team Meeting (August 5, 2025) |
| 2 | + |
| 3 | +## Roll call |
| 4 | + |
| 5 | +(Name / `@GitHubUsername` _[/ Discord, if different]_) |
| 6 | + |
| 7 | +- Hugo van Kemenade / `@hugovk` |
| 8 | +- Ryan Duve / `@ryan-duve` |
| 9 | +- Petr Viktorin / `@encukou` |
| 10 | +- Daniele Procida / `@evildmp` |
| 11 | +- Keith Murray / `@KeithTheEE` |
| 12 | +- Adam Turner / `@AA-Turner` |
| 13 | +- Trey Hunner / `@treyhunner` |
| 14 | +- Blaise Pabon / `@blaisep` / `@controlpl4n3` |
| 15 | +- Ned Batchelder / `@nedbat` |
| 16 | + |
| 17 | +## Reports and celebrations |
| 18 | + |
| 19 | +> 60 second updates on things you have been up to, questions you have, or developments |
| 20 | +> you think people should know about. Please add yourself, and if you do not have an |
| 21 | +> update to share, you can pass. |
| 22 | +
|
| 23 | +> This is a place to make announcements (without a need for discussion). This is also a |
| 24 | +> great place to give shout-outs to contributors! We'll read through these at the |
| 25 | +> beginning of the meeting. |
| 26 | +
|
| 27 | +- July follow-ups: |
| 28 | + - [python/cpython#137131](https://github.com/python/cpython/pull/137131) (_Link to |
| 29 | + plaintext for "show source" links_, by Ryan Duve) |
| 30 | + - [python/cpython#136246](https://github.com/python/cpython/pull/136246) (_Docs: a |
| 31 | + start on an 'improve this page' feature_, by Ned Batchelder) |
| 32 | + - t-string documentation: |
| 33 | + [`string.templatelib` — Support for template string literals](https://docs.python.org/dev/library/string.templatelib.html), |
| 34 | + [template string literal syntax](https://docs.python.org/dev/reference/lexical_analysis.html#t-strings) |
| 35 | +- EuroPython documentation sprints were a success: many new contributors and many new |
| 36 | + PRs |
| 37 | +- PyCon UK sprints |
| 38 | + - Daniele, Hugo, and Adam hope to be there |
| 39 | +- Hugo: We'll alternate meeting times each month to better accommodate people in |
| 40 | + different time zones: even months at the "old" later time, and odd months three hours |
| 41 | + earlier. Let's keep the DST adjustment as before, and try this out until the end of |
| 42 | + the year to see how it goes. |
| 43 | + |
| 44 | +## Discussion |
| 45 | + |
| 46 | +- [Trey] Future topic: merge documentation earlier, at the same time or before code? |
| 47 | +- Hugo: Sebastián Ramírez suggested Documentation Driven Development. |
| 48 | + |
| 49 | +### Topic |
| 50 | + |
| 51 | +- [Ellipsis documentation](https://discuss.python.org/t/99481) |
| 52 | + |
| 53 | + - Should we keep it short and technical (Ellipsis is just an object), or should it |
| 54 | + explain how people use it and give examples? |
| 55 | + |
| 56 | + - Trey: The documentation should ideally give examples of usage. But not too much |
| 57 | + elaboration. |
| 58 | + - Ned: Use in place of `pass` -- we could just use '17' |
| 59 | + - Daniele: didn't realise that `...` was an object; had always seen it as English |
| 60 | + prose. |
| 61 | + - Ned/Trey: the three dots are used for lots of things! We could mention that '...' is |
| 62 | + used for many things, for example, also in doctest, recursive object |
| 63 | + representations, and so on. |
| 64 | + - Adam/Ned: Come up with a rubric that can guide us in future topics, rather than |
| 65 | + specifically about Ellipsis. |
| 66 | + - Trey: idioms & colloquialisms are more missing than he'd like, for example, dunder |
| 67 | + not much use. |
| 68 | + - Hugo: We recently added ~~'Walrus'~~ 'f-string'! |
| 69 | + - Petr: Note that 'idioms' aren't dictated by the language |
| 70 | + - see this note on `_` for prior art: |
| 71 | + <https://docs.python.org/3/reference/lexical_analysis.html#reserved-classes-of-identifiers> |
| 72 | + |
| 73 | +- Traffic and AI search behaviour - follow up on |
| 74 | + [Discord discussion](https://discord.com/channels/935215565872693329/1009192183137566874/1390065560091496499): |
| 75 | + is there evidence that search engines' AI summaries are intercepting users that would |
| 76 | + otherwise reach the documentation? |
| 77 | + |
| 78 | + - Seeing a collapse in traffic to technical content. |
| 79 | + - <https://analytics.python.org/docs.python.org?period=all&keybindHint=A> |
| 80 | + - Ned: Frequently asks Claude instead of using documentation |
| 81 | + - Used when unclear what the solution is / what documentation to use |
| 82 | + - Skipping the search engine entirely |
| 83 | + - Daniele: Does this matter? Should we care? Ned: If it did, what would we do? We're |
| 84 | + not going to take down docs.python.org |
| 85 | + - Daniele: If people aren't even going to docs.python.org, they don't realise who is |
| 86 | + behind the software/documentation. Impact on resourcing for PSF? Like turning on the |
| 87 | + tap, you don't consider where water comes from. |
| 88 | + - Improving documentation might improve LLM results? |
| 89 | + - Do LLMs 'prefer' docs.python.org? |
| 90 | + - Keith: In time, will we see greater use of documentation as more people will be |
| 91 | + building things that are too complex for LLMs? |
| 92 | + |
| 93 | +- Support for non-HTML formats: _Should we bother?_. |
| 94 | + |
| 95 | + - Adam: Builds for PDF/LaTeX/EPUB/Text/Texinfo were unintentionally not working for |
| 96 | + all of May-July. We had minimal complaints, is it worth keeping these formats? |
| 97 | + - Hugo: Some complaints re: EPUB |
| 98 | + - Adam: Perhaps we could just drop PDF? It takes the vast majority of the resources. |
| 99 | + - Followup: <https://discuss.python.org/t/101343/> |
| 100 | + |
| 101 | +- Transifex mis-propagation -- review / lessons learnt. |
| 102 | + - we have a suite of software to sync translations, which had a bad bug. The people |
| 103 | + who know more are not at the meeting. |
| 104 | +- Splitting stdtypes, functions, and so on. |
| 105 | + - they're currently big monoliths. Should we consider splitting them? How do we split |
| 106 | + them? One page per type? One page per group of methods? |
| 107 | + - The current state hurts SEO; splitting might hurt Ctrl+F. |
| 108 | + - We need some sort of plan/information architecture. |
| 109 | +- Concurrency HOWTO ([Eric's PR](https://github.com/python/cpython/pull/123163)) |
| 110 | + |
| 111 | + - Trey: excited to see PR. |
| 112 | + |
| 113 | +- Next month's meeting: 3 hours earlier, at 16:00 UTC. |
0 commit comments