Documentation Community Team Meeting (March 2024)#

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() in Doc/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 italic

    • CAM: 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 and dict? 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.