Documentation Community Team Meeting (September 3, 2024)¶
Roll call¶
(Name / @GitHubUsername [/ Discord, if different])
Daniele Procida /
@EvilDMPHugo van Kemenade /
@hugovkTrey /
@treyhunnerManuel /
@humitosMelissa /
@melissawmPetr Viktorin /
@encukouRyan /
@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://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 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
[Petr] Will merge tomorrow
[Hugo] Matt Layman found that the builtin docs aren’t good for beginners & built a more approachable version
[Trey] I also have a version that leaves things out, built for teaching. It would be nice to have some version of this in the docs. And another cheatsheet.
[Petr] Here’s mine (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”, which can be seen as one big notebook
