|
| 1 | +# Documentation Community Team Meeting (September 2024) |
| 2 | + |
| 3 | +- **Date:** 2024-09-03 |
| 4 | +- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2024-09-03/19:00/Docs%20Meeting) |
| 5 | +- **This HackMD:** <https://hackmd.io/@encukou/pydocswg1> |
| 6 | +- [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-3rd-september-2024/62175) (for September) |
| 7 | +- [**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)) |
| 8 | +- **Calendar event:** (send your e-mail to Mariatta for an invitation) |
| 9 | +- **How to participate:** |
| 10 | + - Go to [Google Meet](https://meet.google.com/dii-qrzf-wkw) and ask to be let in. |
| 11 | + - To edit notes, click the “pencil” or “split view” button on the [HackMD document](https://hackmd.io/@encukou/pydocswg1). |
| 12 | + You need to log in (e.g. with a GitHub account). |
| 13 | + |
| 14 | +By participating in this meeting, you are agreeing to abide by and uphold the [PSF Code of Conduct](https://www.python.org/psf/codeofconduct/). |
| 15 | +Please take a second to read through it! |
| 16 | + |
| 17 | +## Roll call |
| 18 | + |
| 19 | +(Name / `@GitHubUsername` *[/ Discord, if different]*) |
| 20 | + |
| 21 | +- Daniele Procida / @EvilDMP |
| 22 | +- Hugo van Kemenade / @hugovk |
| 23 | +- Trey / @treyhunner |
| 24 | +- Manuel / `@humitos` |
| 25 | +- Melissa / @melissawm |
| 26 | +- Petr Viktorin / @encukou |
| 27 | +- Ryan / `@ryan-duve` |
| 28 | + |
| 29 | +## Discussion |
| 30 | + |
| 31 | +- [Hugo] |
| 32 | + - As a RM, logged into the docs server, and fixed a bunch of stopped jobs |
| 33 | + - It would be nice to have 2 cron jobs -- one for HTML (fast), one for PDFs (slow) |
| 34 | + - 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 |
| 35 | + - Separately, we want to move HTML to Read the Docs, while keeping the ability to build them separately |
| 36 | + |
| 37 | +- Dropping PDF builds - should we drop one of the formats (A4/letter)? |
| 38 | + - [Danilel] PDF is used for e-mail from sales, and for air-gapped environments. |
| 39 | + - [Melissa?] If drop both, would need alternative, such as single page HTML [Petr?] And give some love to the print styles |
| 40 | + - [Trey] Is HTML faster to build? [Hugo] Yes, about 3 mins for HTML compared to 30 min to 2 hours for full set: |
| 41 | + | Start | Language/version | Build | |
| 42 | + | :--------------: | :--------------: |------: | |
| 43 | + | 2024-09-02 23:53 | zh-tw/3.13 | 1h 44m | |
| 44 | + | 2024-09-03 01:39 | zh-cn/3.13 | 1h 32m | |
| 45 | + | 2024-09-03 03:13 | uk/3.13 | 3m | |
| 46 | + | 2024-09-03 03:17 | tr/3.13 | 1h 45m | |
| 47 | + | 2024-09-03 05:04 | pt-br/3.13 | 40m | |
| 48 | + | 2024-09-03 05:45 | pl/3.13 | 33m | |
| 49 | + | 2024-09-03 06:20 | ko/3.13 | 54m | |
| 50 | + | 2024-09-03 07:16 | ja/3.13 | 1h 23m | |
| 51 | + | 2024-09-03 08:40 | it/3.13 | 32m | |
| 52 | + | 2024-09-03 09:13 | id/3.13 | 42m | |
| 53 | + | 2024-09-03 10:25 | es/3.13 | 1h 59m | |
| 54 | + | 2024-09-03 12:25 | en/3.13 | 32m | |
| 55 | + - [Manuel] What's the frequency? [Hugo] 24 hours or more |
| 56 | + - [Manuel] Can we build PDFs less often? People who download them probably read them offline. |
| 57 | + - [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. |
| 58 | + - [Melissa] For NumPy/SciPy there's nothing that can replace LaTeX yet; for other projects it might be similar |
| 59 | + - [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 |
| 60 | +- [Manuel] I saw a closed issue about enabling translations of code blocks. Does anyone here have experience translating code blocks? |
| 61 | + - 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. |
| 62 | + - [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. |
| 63 | + - [Petr] Should we mark the messages and allow translation teams to turn them off? |
| 64 | + - [Manuel] I'll research more about the discussion on GitHub and come back |
| 65 | + |
| 66 | +- [Daniele] I'll be doing a docs workshop @ DjangoCon US. Will anyone here be at that conference? (No ☹) |
| 67 | + |
| 68 | +- [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) |
| 69 | + - [Petr] Will merge tomorrow |
| 70 | + |
| 71 | +- [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/) |
| 72 | + - [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/). |
| 73 | + - [Petr] [Here's mine](https://github.com/pyvec/cheatsheets/blob/master/strings/strings-en.pdf) (the translation isn't great) |
| 74 | + - [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? |
| 75 | + - [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. |
| 76 | + - [Trey] I could help start docs for teaching Python. |
| 77 | + - [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. |
| 78 | + - [Melissa] Matplotlib has cheatsheets, but also has ["handouts"](https://matplotlib.org/cheatsheets/_images/handout-beginner.png), which can be seen as one big notebook |
| 79 | + |
| 80 | +## Follow-ups from previous meeting(s) |
| 81 | + |
| 82 | +*[Monthly reports archive](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html)* |
| 83 | + |
| 84 | +## Next meeting |
| 85 | + |
| 86 | +The docs team generally meets on the first Tuesday of every month around 19:00-ish UTC. |
| 87 | + |
| 88 | +We have a recurring Google Calendar event for the meeting. |
| 89 | +Let Mariatta know your email address and she can invite you. |
0 commit comments