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>