Documentation Community Team Meeting (March 2024)¶
Date: 2024-03-05
Time: 20:00 UTC
This HackMD: https://hackmd.io/@encukou/pydocswg1
Discourse thread (for March)
Meeting reports (the latest one might be an unmerged PR)
Calendar event: (send your e-mail to Mariatta for an invitation)
How to participate:
Go to Google Meet and ask to be let in.
To edit notes, click the “pencil” or “split view” button on the HackMD document. You need to log in (e.g. with a GitHub account).
By participating in this meeting, you are agreeing to abide by and uphold the PSF Code of Conduct. Please take a second to read through it!
Roll call¶
(Name / @GitHubUsername
[/ Discord, if different])
Ege Akman /
@egeakman
Ashley Whetter /
@AWhetter
Carol Willing /
@willingc
Ned Batchelder /
@nedbat
Hugo van Kemenade /
@hugovk
Petr Viktorin /
@encukou
Pradyun /
@pradyunsg
Ezio Melotti /
@ezio-melotti
Erlend Aasland /
@erlend-aasland
CAM /
@CAM-Gerlach
Reports and celebrations¶
Discussion¶
Carol Willing: Changelog splitting/reduction. At the February meeting, we had consensus that slimming down the changelog makes good sense. Let’s discuss the potential approaches to do so, and try to reach consensus.
CAM: split by minor release (feature version) would probably make most sense; we could make it more granular.
Instead of changelog file we could have a changelog directory. Or we could chunk it in the directive. Either way is relatively straightforward.
Ezio: We have to think about the use of this changelog; one of those is searching for a particular module/function across all the releases. If we split it in several files, this’ll be harder. Maybe we should keep a few latest releases on a single page. Or use tabs and make filtering faster.
Hugo: On mobile, the page doesn’t render well.
CAM: Are people searching the rendered HTML, or other files. (Petr: I use Ctrl+F quite often)
Carol: One more use case: When a bug happens, searching for when the feature was introduced.
There are several issues: the time it takes to build, and the performance on mobile.
Pradyun: We could make it so that there’s still a search across changelogs. We could also add some JavaScript to fetch the files and render them in one file.
CAM: Or we could have one file with everything, and multiple per-version files. It’ll still affect build time though.
Ned: What’s the original problem, user experience or build times? Hugo: build time is not the main concern.
Ashley: What are the use cases of the NEWS file over the What’s New pages? Hugo: I only check the What’s New.
Erlend: Do people actually read the changelog, or do they only search it? Does it really have an impact for users if we shorten the changelog?
CAM: Maybe we should look into the stats at Plausible.
Carol: For mobile, data can be expensive and slow, so we want this to be responsive and easy to use.
Hugo: In the Plausible trial, it’s the 256th most visited page (4,000 views). What’s New was number 98 (18,000 views). There are 10,000+ pages (across 3 versions and several translations).
rank, page, views 62 /3/whatsnew/3.11.html 32123 98 /3.12/whatsnew/3.12.html 17967 129 /3.11/whatsnew/3.11.html 11410 140 /3/whatsnew/3.10.html 10199 178 /3/whatsnew/3.8.html 7250 253 /3/whatsnew/3.9.html 4333 256 /3/whatsnew/changelog.html 4226 263 /3.13/whatsnew/3.13.html 4042 277 /3/whatsnew/index.html 3752 435 /zh-cn/3/whatsnew/3.11.html 1993 459 /3/whatsnew/3.6.html 1875 547 /3/whatsnew/3.7.html 1514 553 /3/whatsnew/3.0.html 1488 695 /zh-cn/3/whatsnew/index.html 990
Ned: How are we going to use the numbers?
CAM: The page size for the What’s New is about 3KB, changelog is about 4.6MB. That’s quite big if you’re not on broadband.
Pradyun: It looks like we have agreement for splitting by directory. Any concerns with that?
Petr: If you don’t use a changelog for searching across Python versions, there isn’t much else to use it for.
[note taker was in discussion]
Ezio: Using tabs like we use for the devguide?
Hugo: It would not solve the downloading/page size issue.
Ezio: (paraphrased) It would help the DOM rendering issue.
Action item: @encukou to ask on the issue if there’s a known usecase for the changelog where you don’t want everything on one page.
Erlend: Evaluate param markup for
eval()
inDoc/library/functions.rst
(PR #115212)Erlend: Last year (https://discuss.python.org/t/16090) there was a discussion about why we don’t use markup for arguments. The consensus seemed to be “let’s try it out”. I did, and received mostly positive feedback. Now I changed
eval
needs more attention than some weird corner of the stdlib. I merged it; looking for feedback. I have more functions in the pipeline.Hugo: +1, it’s easier to scan
Erlend: the issue had a very long history with lots of discussion about how to communicate the meaning of the parameters, before we agreed on a wording that everyone liked. Structured parameter docs make this easier.
Ned: I wish we could get away with the Sphinx syntax where colons are brackets somehow.
(Carol: Way back then we didn’t have brackets, remember? :)
CAM: there’s also Myst…
Erlend: Any reservations after seeing it live?
Carol: One of the concerns is consistency across the whole file.
Erlend: That’s a valid concern. Will try to find some time to change the markup for some other functions in the page. It’s not always straightforward to do for some of the more low-level functions like compile.
Hugo: I think it’s good.
Erlend: One aspect is that this simplifies writing the description. It’s more normalized so there isn’t so much space for discussion.
Petr: Maybe we could get a graphic designer comment on the theme.
Hugo: Tania Allard has offered to help with an accessibilty audit which could help
Ned: There are disparate styles:
str
is monospace, code object is italicCAM: We had a big discussion about how to style
None
; decision was to use monospace but not link it. There are differences in the markup too.Ned: Should we link
str
anddict
? We could just use monospace. Sometimes, the docs canbe over-linked.CAM: it’s important to distinguish names that exist in Python.
Carol: Let’s ask a UI expert.
(…)
We should have a cheatsheet for reST. The page in the devguide isn’t clear for newcomers.
CAM: Should we expand the current cheatsheet, or have an expanded “getting started” guide?
Carol: I’m not entirely sure, I’m not making any radical change right now. I was looking into what would be a stumbling point for sprinters and this came up.
CAM: BTW, in the logging docs, formatter parameter types are auto-linked but not monospaced
(discussion on tooling)
Ned: We should start from what we would like to see, and then make the tools do that.
Next meeting¶
The docs team generally meets on the first Tuesday of every month around 20:00-ish UTC.
We have a recurring Google Calendar event for the meeting. Let Mariatta know your email address and she can invite you.