From 7783ca0fbe208630865a853afc134f89eeaea6e6 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 20 Oct 2024 20:42:30 +0300 Subject: [PATCH 1/5] Add October 2024 meeting notes --- docs/monthly-meeting/2024-10.md | 173 ++++++++++++++++++++++++++++++++ docs/monthly-meeting/index.rst | 1 + 2 files changed, 174 insertions(+) create mode 100644 docs/monthly-meeting/2024-10.md diff --git a/docs/monthly-meeting/2024-10.md b/docs/monthly-meeting/2024-10.md new file mode 100644 index 0000000..2997af2 --- /dev/null +++ b/docs/monthly-meeting/2024-10.md @@ -0,0 +1,173 @@ +# Documentation Community Team Meeting (October 2024) + +- **Date:** 2024-10-01 +- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2024-10-01/19:00/Docs%20Meeting) +- **This HackMD:** +- [**Discourse thread**](TODO) (for October) +- [**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]_) + +- Carol Willing `@willingc` +- Ned `@nedbat` +- Melissa `@melissawm` +- Trey +- Ezio Melotti `@ezio-melotti` +- Joe _`@itsthejoker`_ +- Petr Viktorin `@encukou` +- Ryan Duve `@ryan-duve` +- Mariatta + +## Introductions + +> If there are any new people, we should do a round of introductions. + +## 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. + +- Python Docs Editorial Board has meeting minutes published at + https://python.github.io/editorial-board/ + +## Discussion + +- [Ned] Reorganization of the devguide --> Contributor's Guide: + https://github.com/python/devguide/pull/1426 + + - this grew out of a recognition that we want to recognize other types of + contributions than “dev”. + - We had PyCon US attendees playtest a contribution to the docs + - First we wanted a devguide, docs-guide, etc., now we want a common contributor guide + - Carol started a new section, “contrib”, as a staging area for the new content. + Currently it's a section at the end; later the devguide will be replaced by this. + - Ned has been filling “contrib” in -- moving things from devguide to it. + - As part of the existing devguide, this has PR builds on Read the Docs so you can see + the result. + - [Carol] Melissa has been doing great work on design, accessibility, translations... + This contributor guide will also look at different types of contributions. + - [Ned] wrote the outline, but then realized that triaging should be its own top-level + section; translations should be under docs, etc. + - [Melissa] What's the best place for comments? [Ned] Big philosophical questions + should go to discuss.python.org (maybe a new thread). Putting things in the PR isn't + bad either. Existing thread at: + https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409/14 + - [Trey] When should the PR be merged? [Ned] When it's useful. In some sense, _this_ + PR will never be merged. [Carol] can periodically rebase the PR to pull in any new + content. + - [Trey] I want to suggest that it's merged quickly, to avoid a long-lived branch + - [Carol] Maybe we should have a long-running branch called “contrib” where we merge + the new content. + - [Carol] modified the Read the Docs config to build the contrib branch in a separate + place + +- [Mariatta] Starting a tutorials.python.org for Official Python tutorial content. + Follow up from Core Sprint discussion. + - What if our docs looked like this? [astro.build](https://astro.build) (uses + [starlight](https://starlight.astro.build) maybe?) + - A big “get started” button getting you to a selection of tutorials + - Tutorials have interactive quizzes, checklists, progress trackers + - Current tooling does not let us do this. What do we do? How do we move forward? + - At the sprint it was suggested that we probably won't make the docs look like this, + but maybe only the tutorials. + - I'd really like this to be Python docs, not just “Mariatta's tutorial”. It should be + continually maintained by the community. + - [Ned] There are two halves to this proposal -- the site, and the contents of the + tutorial. + - [Mariatta] The current tutorial also needs work, maybe we're constrained by the + current tooling. + - [Carol] The current tutorial has some attachment from long-time core devs, so it's + hard to change. This would be a creative way to introduce something new. + - [Carol] Something I've struggled with is that a wall of text with no interactivity + makes it hard for me to digest the info, so having more modalities could make it + more accessible + - [Melissa] We did this a few years ago with NumPy tutorials. I agree with Mariatta + 100%, but also: we had so many people filing issues caused by reading outdated + tutorials, so we wanted one official place with up-to-date info. We went with a + separate repo, so we could use a different tech stack. We went with a plain theme, + but there are so many themes now, even ones for Sphinx. + - For https://numpy.org/numpy-tutorials/ we went with a separate repo, with a + different technical setup (jupytext - text-based notebooks) + https://github.com/numpy/numpy-tutorials + - [Mariatta] It's great knowing that NumPy went through this path, now we need to do + it for Python. I feel that we don't need Sphinx for tutorials. + - [Trey] Maybe if we don't make it as fancy as astro.build, but get 80% there, it'll + still be a great improvement. + - [Trey] I like things like this when they're very opinionated, ideally _my_ way, + and I guess that's how many tutorials started. To build an opinionated tutorial + together, maybe we should document the opinions we're working with. + - [Joe] I've worked a lot with mkdocs-tutorial, and I found it great. I don't think + we could use it here, because a lot of the functionality is locked behind a very + expensive paywall. (Minimum $125/mo, but would probably be closer to $250/mo. If + we don't want or need any of the fancier features, then free is still an option. + [Sponsorship info](https://squidfunk.github.io/mkdocs-material/insiders/sponsoring-tiers/)) + - [Joe] I'll also advocate for a JavaScript approach to a tutorial. When newcomers + see a page that's technical and dense, they get scared. It'll be easier on them if + we make them transition to information-dense docs. "Pretty and friendly" is more + important. + - [Mariatta] I've also used https://docusaurus.io/ Which is a JavaScript approach. + But in the end I like astro best. + - [Carol] in the past, the biggest change would be Markdown vs. ReST. From + experience with other projects, Markdown lets you have the flexibility to change + tooling if needed, so the display is separate from the content. + - [Carol] Were there concerns at the sprint? + - [Melissa] What Mariatta showed made me thing of learning paths: + https://en.wikipedia.org/wiki/Learning_pathway -- people can start where they + need, depending on how much handholding they need etc. + - [Mariatta] Maybe the first quiz should be “what kind of a learner are you”? + - [Carol] Moving away from the tooling: I thing there's a subset of users that use + the current Python tutorial, others use different ones - Carpentries, ones from + the scientific ecosystem, Dr.Chuck, Chicago[???], etc. The Carpentries have done a + great job in the past decade coming up with learning-theory-based tutorials: + https://carpentries.org/community-lessons/ + - [Mariatta] So what do we do next? + - [Carol] 2 steps: talk about it as EB, but also reach out to Tania & the community + success project, so there's no duplication of effort. In an ideal world, this + would be part of the python.org website, design-wise. + - [Trey] The PSF is trying to answer the question of how do we get more people + on-boarded with Python, this looks like the answer to that. + - [Mariatta] I want to make sure that as folks contribute to this, they feel like + they're collaborating on creating a core piece of Python as opposed to simply + contributing to a third party platform like Udemy. + - [Melissa] In 2020, we started building our own documentation, and the person who + was our first contributor is also now in charge of the docs four years later. + - [Petr] Recognition is required in some form or another. Contributors will seek it + out whether we provide it or not. + - [Ned] If we have new people coming in, I don't think it will be controversial to + have them start contributing elsewhere and maybe eventually moving to the core + developer team. + - [Petr] How much will the communities mingle? The core developers and the + documentation groups have mostly been separate, and will they work together? They + need to talk to each other, otherwise there will be trust issues. Perhaps separate + groups and their own governance is the right way to go. + - [Mariatta] Let's say there's a large change added — how do we communicate between + documentation and core devs that a matching tutorial has been created for this new + change? + - [Petr] There should be a flag on the PEP saying that the documentation group can + appropriately present the change in the docs. + +## 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. diff --git a/docs/monthly-meeting/index.rst b/docs/monthly-meeting/index.rst index 55546d0..68aa5f2 100644 --- a/docs/monthly-meeting/index.rst +++ b/docs/monthly-meeting/index.rst @@ -25,3 +25,4 @@ Monthly reports in chronological order. Jul 2024 <2024-07.md> Aug 2024 <2024-08.md> Sep 2024 <2024-09.md> + Oct 2024 <2024-10.md> From fc8ee32156494f17618fa6fa01096c22ade5dce3 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 20 Oct 2024 20:44:21 +0300 Subject: [PATCH 2/5] Do TODO --- docs/monthly-meeting/2024-10.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/monthly-meeting/2024-10.md b/docs/monthly-meeting/2024-10.md index 2997af2..2d9489c 100644 --- a/docs/monthly-meeting/2024-10.md +++ b/docs/monthly-meeting/2024-10.md @@ -3,7 +3,7 @@ - **Date:** 2024-10-01 - **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2024-10-01/19:00/Docs%20Meeting) - **This HackMD:** -- [**Discourse thread**](TODO) (for October) +- [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-1st-october-2024/65282) (for October) - [**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)) From ac79a672910d515ffd9557d92abbaf64d30c96bb Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 20 Oct 2024 20:48:54 +0300 Subject: [PATCH 3/5] Fix link --- docs/monthly-meeting/2023-01.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/monthly-meeting/2023-01.md b/docs/monthly-meeting/2023-01.md index 0e22192..0aa69d4 100644 --- a/docs/monthly-meeting/2023-01.md +++ b/docs/monthly-meeting/2023-01.md @@ -60,7 +60,7 @@ Please take a second to read through it! ### Python Project Documentation - [Trouble installing Python](https://mail.python.org/archives/list/docs@python.org/thread/I7JDNUYWIZ3QVY33IDYWFKDTZMIPIVNS/) - - [Running scripts with a GUI](https://docs.python.org/3/using/mac.html#running-scripts-with-a-gui) + - [Running scripts with a GUI](https://docs.python.org/3.11/using/mac.html#running-scripts-with-a-gui) - The docs mailing list: - I'm referring to docs@python.org From 48cff149ed52098b2bdd4cc6796ee5b37f3dc2e5 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 20 Oct 2024 20:51:53 +0300 Subject: [PATCH 4/5] Linkify links --- docs/monthly-meeting/2024-10.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/monthly-meeting/2024-10.md b/docs/monthly-meeting/2024-10.md index 2d9489c..32c2a21 100644 --- a/docs/monthly-meeting/2024-10.md +++ b/docs/monthly-meeting/2024-10.md @@ -47,12 +47,12 @@ to read through it! > beginning of the meeting. - Python Docs Editorial Board has meeting minutes published at - https://python.github.io/editorial-board/ + ## Discussion - [Ned] Reorganization of the devguide --> Contributor's Guide: - https://github.com/python/devguide/pull/1426 + [python/devguide#1426](https://github.com/python/devguide/pull/1426) - this grew out of a recognition that we want to recognize other types of contributions than “dev”. @@ -105,9 +105,9 @@ to read through it! tutorials, so we wanted one official place with up-to-date info. We went with a separate repo, so we could use a different tech stack. We went with a plain theme, but there are so many themes now, even ones for Sphinx. - - For https://numpy.org/numpy-tutorials/ we went with a separate repo, with a + - For we went with a separate repo, with a different technical setup (jupytext - text-based notebooks) - https://github.com/numpy/numpy-tutorials + - [Mariatta] It's great knowing that NumPy went through this path, now we need to do it for Python. I feel that we don't need Sphinx for tutorials. - [Trey] Maybe if we don't make it as fancy as astro.build, but get 80% there, it'll @@ -124,21 +124,21 @@ to read through it! see a page that's technical and dense, they get scared. It'll be easier on them if we make them transition to information-dense docs. "Pretty and friendly" is more important. - - [Mariatta] I've also used https://docusaurus.io/ Which is a JavaScript approach. + - [Mariatta] I've also used Which is a JavaScript approach. But in the end I like astro best. - [Carol] in the past, the biggest change would be Markdown vs. ReST. From experience with other projects, Markdown lets you have the flexibility to change tooling if needed, so the display is separate from the content. - [Carol] Were there concerns at the sprint? - [Melissa] What Mariatta showed made me thing of learning paths: - https://en.wikipedia.org/wiki/Learning_pathway -- people can start where they + -- people can start where they need, depending on how much handholding they need etc. - [Mariatta] Maybe the first quiz should be “what kind of a learner are you”? - [Carol] Moving away from the tooling: I thing there's a subset of users that use the current Python tutorial, others use different ones - Carpentries, ones from the scientific ecosystem, Dr.Chuck, Chicago[???], etc. The Carpentries have done a great job in the past decade coming up with learning-theory-based tutorials: - https://carpentries.org/community-lessons/ + - [Mariatta] So what do we do next? - [Carol] 2 steps: talk about it as EB, but also reach out to Tania & the community success project, so there's no duplication of effort. In an ideal world, this From 7d1e921619af4eb556d096c04dc4beac1955f6b7 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Sun, 20 Oct 2024 20:57:33 +0300 Subject: [PATCH 5/5] Fix link --- docs/monthly-meeting/2023-02.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/monthly-meeting/2023-02.md b/docs/monthly-meeting/2023-02.md index bc4f362..09fedec 100644 --- a/docs/monthly-meeting/2023-02.md +++ b/docs/monthly-meeting/2023-02.md @@ -60,7 +60,7 @@ Please take a second to read through it! *For and about the Community or Working Group* - Trouble installing Python: [mail.python.org/archives/list/docs@python.org/thread/I7JDNUYWIZ3QVY33IDYWFKDTZMIPIVNS/](https://mail.python.org/archives/list/docs@python.org/thread/I7JDNUYWIZ3QVY33IDYWFKDTZMIPIVNS/) - - [docs.python.org/3/using/mac.html#running-scripts-with-a-gui](https://docs.python.org/3/using/mac.html#running-scripts-with-a-gui) + - [docs.python.org/3/using/mac.html#running-scripts-with-a-gui](https://docs.python.org/3.11/using/mac.html#running-scripts-with-a-gui) - Overhaul Building the Documentation section for clarity - [python/devguide#1038](https://github.com/python/devguide/pull/1038)