Create April 2024 minutes

[hugovk]

Dump of April's https://hackmd.io/@encukou/pydocswg1 so we can re-use the HackMD for May.

Let's edit and add to https://github.com/python/docs-community/tree/main/docs/monthly-meeting

# Documentation Community Team Meeting (April 2024)

:::info
- **Date:** 2024-04-02
- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2024-04-02/19:00/Docs%20Meeting)
- **This HackMD:** https://hackmd.io/@encukou/pydocswg1
- [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-2nd-april-2024/49574) (for April)
- [**Meeting reports**](https://docs-community.readthedocs.io/en/latest/monthly-meeting/) (the latest one might be an [**unmerged PR**](https://github.com/python/docs-community/pulls))
- **Calendar event:** (send your e-mail to Mariatta for an invitation)
- **How to participate:**
  -  Go to [Google Meet](https://meet.google.com/dii-qrzf-wkw) and ask to be let in.
  -  To edit notes, click the “pencil” or “split view” button on the [HackMD document](https://hackmd.io/@encukou/pydocswg1). 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](https://www.python.org/psf/codeofconduct/).
Please take a second to read through it!


## Roll call

(Name / `@GitHubUsername` *[/ Discord, if different]*)

- Petr Viktorin / `@encukou`
- Hugo van Kemenade / `hugovk`
- Daniele
- Carol / `@willingc`
- Ned / `@nedbat`
- CAM / `@CAM-Gerlach`
- Bradley
- Ashley / `@AWhetter`
- 


## 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.

- [Carol] Docs summit at PyCon US https://us.pycon.org/2024/events/hatchery/docs-summit/
- [Hugo] Modernised font on macOS: [python/python-docs-theme#176](https://github.com/python/python-docs-theme/pull/176)
- [Hugo] I wrote up how to activate tabs in Sphinx docs based on the reader's OS: https://dev.to/hugovk/sphinx-docs-how-to-activate-tabs-for-your-os-pd3
- [Hugo] Python 3.11 is now only accepting security fixes, so very few docs PRs need backporting: https://devguide.python.org/versions/


## Discussion

### Changelog splitting/reduction

No use cases other than "grepping it all" found so far

### [CAM] WarningMessage is undocumented

https://discuss.python.org/t/warningmessage-is-undocumented/48877

Please read the thread and chime in!

### Parameter annotations: `int | float` or `int or float`?

https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196


- [Name] ...


### 'Internal' items

*For and about the Community or Working Group*

- [Name] ...

### Python Project Documentation

*Relating to `docs.python.org`, `peps.python.org`, `devguide.python.org`, etc.*

- [Name] ...

### PEP Workflow

- [Name] ...

## Follow-ups from previous meeting(s)

*[Monthly reports archive](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html)*

- [name=Carol Willing]: [Changelog splitting/reduction](https://github.com/python/docs-community/issues/98). 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 thing 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.


- [name=Erlend Aasland]: Evaluate param markup for `eval()` in `Doc/library/functions.rst` (PR [#115212](https://github.com/python/cpython/pull/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 19:00-ish UTC.

We have a recurring Google Calendar event for the meeting.
Let Mariatta know your email address and she can invite you.

[encukou]

PR here: #114