# 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).
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)
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
commented
6 months ago
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
[name=Erlend Aasland]: Evaluate param markup for
eval()inDoc/library/functions.rst(PR #115212)evalneeds more attention than some weird corner of the stdlib. I merged it; looking for feedback. I have more functions in the pipeline.stris monospace, code object is italicNone; decision was to use monospace but not link it. There are differences in the markup too.stranddict? We could just use monospace. Sometimes, the docs canbe over-linked.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.