Documentation Community Team Meeting (June 4, 2024)¶
Roll call¶
(Name / @GitHubUsername [/ Discord, if different])
Petr Viktorin /
@encukouEric
Hugo van Kemenade /
@hugovkEzio /
@ezio-melottiAdam
Carol /
@willingcRyan Duve /
@ryan-duveBradley Reynolds /
@shenanigansdErlend /
@erlend-aaslandMarcus Sherman /
@betteridiot
Introductions¶
If there are any new people, we should do a round of introductions.
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.
🇮🇹 “Benvenuti! Questa è la documentazione di Python 3.12.3.” The Python docs are now officially available in Italian! 🚀 docs.python.org/it/3/
Discussion¶
[Hugo] Plausible stats update python/cpython#119977, 2023 trial data: hugovk/plausible-stats
Julien would like to have this only on the official site, not on local or redistributor builds
We could merge the PR right away and then set up an env variable, but it would probably be better to merge with this already set up
[Carol]
PyCon Highlights
Dinner with cross-section of core devs, educators, and authors
Sprint contribute to docs feedback
Sprint discussions
Editorial Board Repo (share feedback here)
Open an issue to ask for a decision
Moving docs from Google Drive to the repo for visibility
If folks get blocked, opening an issue on the EB repo is a good way to get in touch.
The devguide serves the core dev community more than the general docs community. We’ll want to put guidelines in the docs repo instead. We’ll move slow enough to not disrupt the devguide. We’ll make it accessible to folks who want to contribute more frequently.
[Hugo] Yes, the first step in the devguide is to build CPython. Not ideal
[Carol] We had folks like Melanie and Shauna go through the guide and take notes. We’re planning to put the guide on docsguide.python.org; open it up.
Feel free to open issues on the EB repo to give Ned notes & feedback.
Packaging summit: we’re serving 2 groups of users with packaging: producers and consumers. There was some discussion about user research, to make it easier to install packages etc., going through user personas, etc. A “user success” working group is being set up with the PSF.
Maybe the crossover with Docs is helping newcomers.
Python Project Documentation¶
Relating to docs.python.org, peps.python.org, devguide.python.org, etc.
[Blaise] Shall we move the deprecations and removals content out of the News file? Discourse
pytest has separate pages for deprecations
CAM is working on automating some of this
As a user, I’m looking at what’s changing now and what’s planned to change, so I can plan easily. How do I find that easily?
Is it possible to include all of these from a single source, and still show it in all the What’s new documents?
[Hugo] Might have a go at this at some point
[Eric] I’ve always appreciated the structure of the What’s New
Parameter annotations:
int | floatorint or float?discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196
[Erlend] My suggestion is spelling things with words. Very often the types aren’t formal type hints, so in makes sense to spell “or” rather than use the
|notation.[Hugo] You could always ask the Editorial Board
[Carol] Guido will probably have the strongest opinion, but he might be out of reach for some time.
[Adam] We should ground ourselves in user experience. For newcomers arcane language is a barrier. If we’re already on the edge we should prioritize beginners.
But we should also make things better for experienced devs – namely, make the reference docs accurate.
[Adam] Reference docs must be accurate, or overall trust in documentation will decline.
[Eric] The 3 personas are good, but there are others: scientists who don’t want to become programmers, etc. Are there any plans to support these groups?
[Carol] I view that as additional axis to split the user base. We discussed this, but aren’t sure how to language this yet, other than just mention it.
[Hugo] Read the Docs migration
we found a few bugs in RTD, some have been fixed, we should be good to continue.
Packaging user docs
not in the purview of the Docs EB
[Marcus] From an instructional standpoint, the EB guiding principles are very comforting. People jumping into programming from e.g. Excel struggle with e.g.
logging. It’s great that we’re now focusing more on editorial issues instead of just the infrastructure.[Ryan] Should we put examples in docstrings? They are very helpful
[Hugo] We’ve historically intentionally kept docstrings shorter. The Python documentation is duplicated – both in the docstrings and the main docs.
[Ezio] Docstrings should just serve as quick reminders, they are not supposed to be exhaustive.
[Carol] Some of my thoughts are framed from Jupyter & intellisense experience. Historically, info under hover came from the docstrings. It’s not the only possible source. Guido was against docstrings being in scope for the EB. There might be ways to get the docs info into the interactive help.
[Adam] I emphasize with the desire to keep docstrings shorter. I notice that if you open
re, there’s a link to the docs but if you dohelp(re.search)it’s just the signature and some info. Maybe we should add more links to enhance discoverability and reduce duplication.