# Documentation Community Team Meeting (October 2024)

:::info
- **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 Tanya & 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.

### Python Project Documentation

*Relating to `docs.python.org`, `peps.python.org`, `devguide.python.org`, etc.*

- [Name] ...

### 'Internal' items

*For and about the Community or Working Group*

- [Name] ...

### PEP Workflow

- [Name] ...

## Follow-ups from previous meeting(s)

- [Name] ...

*[Monthly reports archive](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html)*

## 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.