Documentation Community Team Meeting (August 5, 2025)¶
Roll call¶
(Name / @GitHubUsername [/ Discord, if different])
Hugo van Kemenade /
@hugovkRyan Duve /
@ryan-duvePetr Viktorin /
@encukouDaniele Procida /
@evildmpKeith Murray /
@KeithTheEEAdam Turner /
@AA-TurnerTrey Hunner /
@treyhunnerBlaise Pabon /
@blaisep/@controlpl4n3Ned 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 (Link to plaintext for “show source” links, by Ryan Duve)
python/cpython#136246 (Docs: a start on an ‘improve this page’ feature, by Ned Batchelder)
t-string documentation:
string.templatelib— Support for template string literals, template string literal syntax
EuroPython documentation sprints were a success: many new contributors and many new PRs
PyCon UK sprints
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 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¶
-
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: 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.
Followup: https://discuss.python.org/t/101343/
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)
Trey: excited to see PR.
Next month’s meeting: 3 hours earlier, at 16:00 UTC.