From e1660b24d07382853939a69357b8d50c91995f3d Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Tue, 7 Jan 2025 21:17:57 +0000 Subject: [PATCH 1/4] Minutes from January 2025 --- docs/monthly-meeting/2025-01.md | 100 ++++++++++++++++++++++++++++++++ docs/monthly-meeting/index.rst | 1 + 2 files changed, 101 insertions(+) create mode 100644 docs/monthly-meeting/2025-01.md diff --git a/docs/monthly-meeting/2025-01.md b/docs/monthly-meeting/2025-01.md new file mode 100644 index 0000000..e62f28d --- /dev/null +++ b/docs/monthly-meeting/2025-01.md @@ -0,0 +1,100 @@ +# Documentation Community Team Meeting (January 2025) + +- **Date:** 2025-01-07 +- **Time:** [20:00 UTC](https://arewemeetingyet.com/UTC/2024-11-05/20:00/Docs20Meeting) +- **This HackMD:** +- [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-7th-january-2025/75975) (for January) +- [**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:** + - We are using Discord: https://discord.gg/RxKXyPYV?event=1303462925834522666 + - 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]*) + +- Adam / `@AA-Turner` +- Hugo / `@hugovk` +- Petr Viktorin / `@encukou` +- Trey Hunner / `@treyhunner` +- Keith / `@KeithTheEE` +- Ryan Duve / `@ryan-duve` +- Sherry +- Blaise / `@blaisep` +- Stan Ulbrych / `@StanFromIreland` + + +## Introductions + +> If there are any new people, we should do a round of introductions. + +This was Sherry's first meeting, introductions were made. + + +## 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. + +- 🇵🇱 "Witamy! To jest oficjalna dokumentacja Pythona 3.13.1." The Python docs are now officially available in Polish! 🚀 [docs.python.org/pl/3/](https://docs.python.org/pl/3/) + + +## Discussion + +### Translations + +- Should we change the translation progress limit for being included in the language switcher? + - This is currently the tutorial and the bugs and functions pages. + - Brief discussion on this threshold, no strong desire to change. +- [Adam] Introduce a page for translation progress, like [React's](https://translations.react.dev/), it just needs to be wired up. + - There's already [Maciej's page](https://m-aciek.github.io/pydocs-translation-dashboard/) + - Issue created: [docs-community#143](https://github.com/python/docs-community/issues/143) + - Action: link Maciej's page from the devguide. + - Action: Add links to contribute. + - Action: Look to move to `https://docs.python.org/translations` (via `docsbuild-scripts`)? +- [Adam] Fate of the language switcher? + - Not very maintainable or good for accessibility. It might be better to have a page for choosing languages. + - Other docs are fairly evenly split between a page to choose and a language switcher per page. + - Switching to the *current* page in another language might be important. + - Seek feedback from those that use the switcher or frequently read non-English documentation. + +### Grammar documentation & Sphinx directives + +- Petr and Blaise have been working on an improved version of Sphinx's `production-list` directive to represent and document Python's grammar. +- Petr provided a demonstration of his work. +- There is an initial PR to add the directives at [#127835](https://github.com/python/cpython/pull/127835) +- This initially adds the directive, grammar snippets (and the surrounding prose) will be converted later, potentially looking to make this automatic. + +### Docs for beginners + +- Can we break up the work so people can contribute in parallel? +- Is this better on `docs.python.org`, or third parties (O'Reilly, w3schools, etc.)? + - Probably better *started* as a third-party effort, so you don't need approvals up-front. (That's also how additions to stdlib should work. Or the translation status page.) + - Third parties know their audience better, and can serve more diverse audiences. + - Tutorials need to cater to many different audiences (children in schools, scientists in labs, experienced programmers from other languages, those entirely new to programming), this might be better accomplished by third parties. +- Many people start with the python.org tutorial, and some “bounce off” and go to another tutorial or leave Python entirely. + - The existing tutorial is targeted at experienced programmers. + - Link to other tutorials (without endorsing)? +- Mariatta was driving the effort. + + +### Python Project Documentation + +*Relating to `docs.python.org`, `peps.python.org`, `devguide.python.org`, etc.* + +- [bswck] Track upstream->downstream translation block update alerts + - Not discussed. + + +## Next meeting + +The docs team generally meets on the first Tuesday of every month around 20:00-ish UTC. + +We have a recurring Google Calendar event for the meeting. +Let Mariatta know your email address and she can invite you. diff --git a/docs/monthly-meeting/index.rst b/docs/monthly-meeting/index.rst index e927126..59f6ef3 100644 --- a/docs/monthly-meeting/index.rst +++ b/docs/monthly-meeting/index.rst @@ -28,3 +28,4 @@ Monthly reports in chronological order. Oct 2024 <2024-10.md> Nov 2024 <2024-11.md> Dec 2024 <2024-12.md> + Jan 2025 <2025-01.md> From 358d065628324b050d9aad1372ab5d628a2b836e Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Tue, 7 Jan 2025 21:21:25 +0000 Subject: [PATCH 2/4] whitespace --- docs/monthly-meeting/2025-01.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/monthly-meeting/2025-01.md b/docs/monthly-meeting/2025-01.md index e62f28d..9632e6a 100644 --- a/docs/monthly-meeting/2025-01.md +++ b/docs/monthly-meeting/2025-01.md @@ -88,7 +88,7 @@ This was Sherry's first meeting, introductions were made. *Relating to `docs.python.org`, `peps.python.org`, `devguide.python.org`, etc.* -- [bswck] Track upstream->downstream translation block update alerts +- [bswck] Track upstream->downstream translation block update alerts - Not discussed. From 495aa61acdac8a39b599a0e279d01e0213a3185d Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Wed, 8 Jan 2025 11:51:24 +0000 Subject: [PATCH 3/4] Hugo's notes Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- docs/monthly-meeting/2025-01.md | 16 ++++------------ 1 file changed, 4 insertions(+), 12 deletions(-) diff --git a/docs/monthly-meeting/2025-01.md b/docs/monthly-meeting/2025-01.md index 9632e6a..6fb3ad2 100644 --- a/docs/monthly-meeting/2025-01.md +++ b/docs/monthly-meeting/2025-01.md @@ -7,7 +7,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)) - **Calendar event:** (send your e-mail to Mariatta for an invitation) - **How to participate:** - - We are using Discord: https://discord.gg/RxKXyPYV?event=1303462925834522666 + - We are using Discord: - 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/). @@ -19,7 +19,7 @@ Please take a second to read through it! (Name / `@GitHubUsername` *[/ Discord, if different]*) - Adam / `@AA-Turner` -- Hugo / `@hugovk` +- Hugo van Kemenade / `@hugovk` - Petr Viktorin / `@encukou` - Trey Hunner / `@treyhunner` - Keith / `@KeithTheEE` @@ -68,10 +68,10 @@ This was Sherry's first meeting, introductions were made. - Petr and Blaise have been working on an improved version of Sphinx's `production-list` directive to represent and document Python's grammar. - Petr provided a demonstration of his work. -- There is an initial PR to add the directives at [#127835](https://github.com/python/cpython/pull/127835) +- There is an initial PR to add the directives at [python/cpython#127835](https://github.com/python/cpython/pull/127835) - This initially adds the directive, grammar snippets (and the surrounding prose) will be converted later, potentially looking to make this automatic. -### Docs for beginners +### Tutorial for beginners - Can we break up the work so people can contribute in parallel? - Is this better on `docs.python.org`, or third parties (O'Reilly, w3schools, etc.)? @@ -84,14 +84,6 @@ This was Sherry's first meeting, introductions were made. - Mariatta was driving the effort. -### Python Project Documentation - -*Relating to `docs.python.org`, `peps.python.org`, `devguide.python.org`, etc.* - -- [bswck] Track upstream->downstream translation block update alerts - - Not discussed. - - ## Next meeting The docs team generally meets on the first Tuesday of every month around 20:00-ish UTC. From e7e60b325e6bbc4bbabfa16736a4f72073173a74 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Wed, 8 Jan 2025 11:51:40 +0000 Subject: [PATCH 4/4] Update docs/monthly-meeting/2025-01.md --- docs/monthly-meeting/2025-01.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/monthly-meeting/2025-01.md b/docs/monthly-meeting/2025-01.md index 6fb3ad2..6fb9a36 100644 --- a/docs/monthly-meeting/2025-01.md +++ b/docs/monthly-meeting/2025-01.md @@ -18,7 +18,7 @@ Please take a second to read through it! (Name / `@GitHubUsername` *[/ Discord, if different]*) -- Adam / `@AA-Turner` +- Adam Turner / `@AA-Turner` - Hugo van Kemenade / `@hugovk` - Petr Viktorin / `@encukou` - Trey Hunner / `@treyhunner`