-
-
Notifications
You must be signed in to change notification settings - Fork 24
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
174 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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:** <https://hackmd.io/@encukou/pydocswg1> | ||
| - [**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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters