Add September 2024 meeting notes

docs/conf.py

@@ -52,10 +52,11 @@
 
 # A list of patterns to ignore when checking for broken links
 linkcheck_ignore = [
+    # The crawler gets "Anchor not found"
+    r"https://github.com.+?#.*",
+    r"https://hackmd\.io/[^?]+\?[^#]+#.+",
     # RTD preview builds:
     r"https://[a-zA-Z0-9.-]+\.org\.readthedocs\.build/[a-zA-Z0-9.-]+/[a-zA-Z0-9.-]+/",
     # Deleted Plausible page:
     r"https://plausible\.io/share/hugovk-cpython\.readthedocs\.io\?auth=XDF9fK3EB2dEHCr4sC9hn",
-    # HackMD anchors:
-    r"https://hackmd\.io/[^?]+\?[^#]+#.+",
 ]

docs/monthly-meeting/2024-09.md

@@ -0,0 +1,89 @@
+# Documentation Community Team Meeting (September 2024)
+
+- **Date:** 2024-09-03
+- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2024-09-03/19:00/Docs%20Meeting)
+- **This HackMD:** <https://hackmd.io/@encukou/pydocswg1>
+- [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-3rd-september-2024/62175) (for September)
+- [**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]*)
+
+- Daniele Procida / @EvilDMP
+- Hugo van Kemenade / @hugovk
+- Trey / @treyhunner
+- Manuel / `@humitos`
+- Melissa / @melissawm
+- Petr Viktorin / @encukou
+- Ryan / `@ryan-duve`
+
+## Discussion
+
+- [Hugo]
+  - As a RM, logged into the docs server, and fixed a bunch of stopped jobs
+  - It would be nice to have 2 cron jobs -- one for HTML (fast), one for PDFs (slow)
+  - We have a bus factor for the repo; only 2 active people; we should give access to more people & we should give Adam access to the build server
+  - Separately, we want to move HTML to Read the Docs, while keeping the ability to build them separately
+
+- Dropping PDF builds - should we drop one of the formats (A4/letter)?
+  - [Danilel] PDF is used for e-mail from sales, and for air-gapped environments.
+  - [Melissa?] If drop both, would need alternative, such as single page HTML [Petr?] And give some love to the print styles
+  - [Trey] Is HTML faster to build? [Hugo] Yes, about 3 mins for HTML compared to 30 min to 2 hours for full set:
+    |      Start       | Language/version |  Build |
+    | :--------------: | :--------------: |------: |
+    | 2024-09-02 23:53 |    zh-tw/3.13    | 1h 44m |
+    | 2024-09-03 01:39 |    zh-cn/3.13    | 1h 32m |
+    | 2024-09-03 03:13 |     uk/3.13      |     3m |
+    | 2024-09-03 03:17 |     tr/3.13      | 1h 45m |
+    | 2024-09-03 05:04 |    pt-br/3.13    |    40m |
+    | 2024-09-03 05:45 |     pl/3.13      |    33m |
+    | 2024-09-03 06:20 |     ko/3.13      |    54m |
+    | 2024-09-03 07:16 |     ja/3.13      | 1h 23m |
+    | 2024-09-03 08:40 |     it/3.13      |    32m |
+    | 2024-09-03 09:13 |     id/3.13      |    42m |
+    | 2024-09-03 10:25 |     es/3.13      | 1h 59m |
+    | 2024-09-03 12:25 |     en/3.13      |    32m |
+  - [Manuel] What's the frequency? [Hugo] 24 hours or more
+  - [Manuel] Can we build PDFs less often? People who download them probably read them offline.
+  - [Melissa] What about rinohtype? [brechtm/rinohtype](https://github.com/brechtm/rinohtype) <https://www.mos6581.org/rinohtype/master/> [Daniele] It's as slow as LaTeX; the typesetting quality should be comparable.
+  - [Melissa] For NumPy/SciPy there's nothing that can replace LaTeX yet; for other projects it might be similar
+  - [Manuel] Do we know download numbers for PDFs? I know it's possible because we are using Plausible events on Read the Docs, but I don't know how to do it. [Here is the code](https://github.com/readthedocs/website/blob/a8af8dedf1fa988f2f35002eea88cfb84c79419f/src/js/site.js#L136) we are using in case we want to do something similar or research a little more
+- [Manuel] I saw a closed issue about enabling translations of code blocks. Does anyone here have experience translating code blocks?
+  - Best practice seems to be translating comments and string literals, but not class/variable names. But if the translator isn't a Python developer, it's hard to follow this. Sometimes the translated code doesn't work.
+  - [Melissa] A lot depends on the tooling and how much context you get. Do translators see the whole code block? [Manuel] Yes, one message contains the whole code.
+  - [Petr] Should we mark the messages and allow translation teams to turn them off?
+  - [Manuel] I'll research more about the discussion on GitHub and come back
+
+- [Daniele] I'll be doing a docs workshop @ DjangoCon US. Will anyone here be at that conference? (No ☹)
+
+- [Ryan] A while ago we talked about improving docs about callables in JSON docs. There's a PR waiting to be merged. [python/cpython#123394](https://github.com/python/cpython/pull/123394)
+  - [Petr] Will merge tomorrow
+
+- [Hugo] Matt Layman found that the builtin docs aren't good for beginners & built [a more approachable version](https://www.mattlayman.com/blog/2024/layman-guide-python-built-in-functions/)
+  - [Trey] I also have [a version](https://pym.dev/built-in-functions-in-python/) that leaves things out, built for teaching. It would be nice to have some version of this in the docs. And another [cheatsheet](https://pym.dev/string-methods/).
+  - [Petr] [Here's mine](https://github.com/pyvec/cheatsheets/blob/master/strings/strings-en.pdf) (the translation isn't great)
+  - [Trey] There are dense parts of the docs that people land on. What's the consensus for updating that? What should we do with string methods, for example? Would a PR be welcome?
+  - [Daniele] I think Matt's instinct is right. If you want a 12-year-old to understand what a "pivot" is, you wouldn't send them to the reference dictionary for a precise definition, history of the word, etc. They want a definition, but a simplified one. Perhaps they need a cheatsheet.
+  - [Trey] I could help start docs for teaching Python.
+  - [Hugo] Where should this go structure-wise? [Daniele] Reference. It could be next to the full reference docs. It should be linked to the full reference.
+  - [Melissa] Matplotlib has cheatsheets, but also has ["handouts"](https://matplotlib.org/cheatsheets/_images/handout-beginner.png), which can be seen as one big notebook
+
+## Follow-ups from previous meeting(s)
+
+*[Monthly reports archive](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html)*
+
+## 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.

docs/monthly-meeting/index.rst

@@ -24,3 +24,4 @@ Monthly reports in chronological order.
    Jun 2024 <2024-06.md>
    Jul 2024 <2024-07.md>
    Aug 2024 <2024-08.md>
+   Sep 2024 <2024-09.md>