# Documentation Community Team Meeting (September 3, 2024)


## 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 an 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)*