|
| 1 | +# Documentation Community Team Meeting (October 2024) |
| 2 | + |
| 3 | +- **Date:** 2024-10-01 |
| 4 | +- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2024-10-01/19:00/Docs%20Meeting) |
| 5 | +- **This HackMD:** <https://hackmd.io/@encukou/pydocswg1> |
| 6 | +- [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-1st-october-2024/65282) (for October) |
| 7 | +- [**Meeting reports**](https://docs-community.readthedocs.io/en/latest/monthly-meeting/) |
| 8 | + (the latest one might be an |
| 9 | + [**unmerged PR**](https://github.com/python/docs-community/pulls)) |
| 10 | +- **Calendar event:** (send your e-mail to Mariatta for an invitation) |
| 11 | +- **How to participate:** |
| 12 | + - Go to [Google Meet](https://meet.google.com/dii-qrzf-wkw) and ask to be let in. |
| 13 | + - To edit notes, click the “pencil” or “split view” button on the |
| 14 | + [HackMD document](https://hackmd.io/@encukou/pydocswg1). You need to log in (e.g. |
| 15 | + with a GitHub account). |
| 16 | + |
| 17 | +By participating in this meeting, you are agreeing to abide by and uphold the |
| 18 | +[PSF Code of Conduct](https://www.python.org/psf/codeofconduct/). Please take a second |
| 19 | +to read through it! |
| 20 | + |
| 21 | +## Roll call |
| 22 | + |
| 23 | +(Name / `@GitHubUsername` _[/ Discord, if different]_) |
| 24 | + |
| 25 | +- Carol Willing `@willingc` |
| 26 | +- Ned `@nedbat` |
| 27 | +- Melissa `@melissawm` |
| 28 | +- Trey |
| 29 | +- Ezio Melotti `@ezio-melotti` |
| 30 | +- Joe _`@itsthejoker`_ |
| 31 | +- Petr Viktorin `@encukou` |
| 32 | +- Ryan Duve `@ryan-duve` |
| 33 | +- Mariatta |
| 34 | + |
| 35 | +## Introductions |
| 36 | + |
| 37 | +> If there are any new people, we should do a round of introductions. |
| 38 | +
|
| 39 | +## Reports and celebrations |
| 40 | + |
| 41 | +> 60 second updates on things you have been up to, questions you have, or developments |
| 42 | +> you think people should know about. Please add yourself, and if you do not have an |
| 43 | +> update to share, you can pass. |
| 44 | +
|
| 45 | +> This is a place to make announcements (without a need for discussion). This is also a |
| 46 | +> great place to give shout-outs to contributors! We'll read through these at the |
| 47 | +> beginning of the meeting. |
| 48 | +
|
| 49 | +- Python Docs Editorial Board has meeting minutes published at |
| 50 | + <https://python.github.io/editorial-board/> |
| 51 | + |
| 52 | +## Discussion |
| 53 | + |
| 54 | +- [Ned] Reorganization of the devgu
6D40
ide --> Contributor's Guide: |
| 55 | + [python/devguide#1426](https://github.com/python/devguide/pull/1426) |
| 56 | + |
| 57 | + - this grew out of a recognition that we want to recognize other types of |
| 58 | + contributions than “dev”. |
| 59 | + - We had PyCon US attendees playtest a contribution to the docs |
| 60 | + - First we wanted a devguide, docs-guide, etc., now we want a common contributor guide |
| 61 | + - Carol started a new section, “contrib”, as a staging area for the new content. |
| 62 | + Currently it's a section at the end; later the devguide will be replaced by this. |
| 63 | + - Ned has been filling “contrib” in -- moving things from devguide to it. |
| 64 | + - As part of the existing devguide, this has PR builds on Read the Docs so you can see |
| 65 | + the result. |
| 66 | + - [Carol] Melissa has been doing great work on design, accessibility, translations... |
| 67 | + This contributor guide will also look at different types of contributions. |
| 68 | + - [Ned] wrote the outline, but then realized that triaging should be its own top-level |
| 69 | + section; translations should be under docs, etc. |
| 70 | + - [Melissa] What's the best place for comments? [Ned] Big philosophical questions |
| 71 | + should go to discuss.python.org (maybe a new thread). Putting things in the PR isn't |
| 72 | + bad either. Existing thread at: |
| 73 | + https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409/14 |
| 74 | + - [Trey] When should the PR be merged? [Ned] When it's useful. In some sense, _this_ |
| 75 | + PR will never be merged. [Carol] can periodically rebase the PR to pull in any new |
| 76 | + content. |
| 77 | + - [Trey] I want to suggest that it's merged quickly, to avoid a long-lived branch |
| 78 | + - [Carol] Maybe we should have a long-running branch called “contrib” where we merge |
| 79 | + the new content. |
| 80 | + - [Carol] modified the Read the Docs config to build the contrib branch in a separate |
| 81 | + place |
| 82 | + |
| 83 | +- [Mariatta] Starting a tutorials.python.org for Official Python tutorial content. |
| 84 | + Follow up from Core Sprint discussion. |
| 85 | + - What if our docs looked like this? [astro.build](https://astro.build) (uses |
| 86 | + [starlight](https://starlight.astro.build) maybe?) |
| 87 | + - A big “get started” button getting you to a selection of tutorials |
| 88 | + - Tutorials have interactive quizzes, checklists, progress trackers |
| 89 | + - Current tooling does not let us do this. What do we do? How do we move forward? |
| 90 | + - At the sprint it was suggested that we probably won't make the docs look like this, |
| 91 | + but maybe only the tutorials. |
| 92 | + - I'd really like this to be Python docs, not just “Mariatta's tutorial”. It should be |
| 93 | + continually maintained by the community. |
| 94 | + - [Ned] There are two halves to this proposal -- the site, and the contents of the |
| 95 | + tutorial. |
| 96 | + - [Mariatta] The current tutorial also needs work, maybe we're constrained by the |
| 97 | + current tooling. |
| 98 | + - [Carol] The current tutorial has some attachment from long-time core devs, so it's |
| 99 | + hard to change. This would be a creative way to introduce something new. |
| 100 | + - [Carol] Something I've struggled with is that a wall of text with no interactivity |
| 101 | + makes it hard for me to digest the info, so having more modalities could make it |
| 102 | + more accessible |
| 103 | + - [Melissa] We did this a few years ago with NumPy tutorials. I agree with Mariatta |
| 104 | + 100%, but also: we had so many people filing issues caused by reading outdated |
| 105 | + tutorials, so we wanted one official place with up-to-date info. We went with a |
| 106 | + separate repo, so we could use a different tech stack. We went with a plain theme, |
| 107 | + but there are so many themes now, even ones for Sphinx. |
| 108 | + - For <https://numpy.org/numpy-tutorials/> we went with a separate repo, with a |
| 109 | + different technical setup (jupytext - text-based notebooks) |
| 110 | + <https://github.com/numpy/numpy-tutorials> |
| 111 | + - [Mariatta] It's great knowing that NumPy went through this path, now we need to do |
| 112 | + it for Python. I feel that we don't need Sphinx for tutorials. |
| 113 | + - [Trey] Maybe if we don't make it as fancy as astro.build, but get 80% there, it'll |
| 114 | + still be a great improvement. |
| 115 | + - [Trey] I like things like this when they're very opinionated, ideally _my_ way, |
| 116 | + and I guess that's how many tutorials started. To build an opinionated tutorial |
| 117 | + together, maybe we should document the opinions we're working with. |
| 118 | + - [Joe] I've worked a lot with mkdocs-tutorial, and I found it great. I don't think |
| 119 | + we could use it here, because a lot of the functionality is locked behind a very |
| 120 | + expensive paywall. (Minimum $125/mo, but would probably be closer to $250/mo. If |
| 121 | + we don't want or need any of the fancier features, then free is still an option. |
| 122 | + [Sponsorship info](https://squidfunk.github.io/mkdocs-material/insiders/sponsoring-tiers/)) |
| 123 | + - [Joe] I'll also advocate for a JavaScript approach to a tutorial. When newcomers |
| 124 | + see a page that's technical and dense, they get scared. It'll be easier on them if |
| 125 | + we make them transition to information-dense docs. "Pretty and friendly" is more |
| 126 | + important. |
| 127 | + - [Mariatta] I've also used <https://docusaurus.io/> Which is a JavaScript approach. |
| 128 | + But in the end I like astro best. |
| 129 | + - [Carol] in the past, the biggest change would be Markdown vs. ReST. From |
| 130 | + experience with other projects, Markdown lets you have the flexibility to change |
| 131 | + tooling if needed, so the display is separate from the content. |
| 132 | + - [Carol] Were there concerns at the sprint? |
| 133 | + - [Melissa] What Mariatta showed made me thing of learning paths: |
| 134 | + <https://en.wikipedia.org/wiki/Learning_pathway> -- people can start where they |
| 135 | + need, depending on how much handholding they need etc. |
| 136 | + - [Mariatta] Maybe the first quiz should be “what kind of a learner are you”? |
| 137 | + - [Carol] Moving away from the tooling: I thing there's a subset of users that use |
| 138 | + the current Python tutorial, others use different ones - Carpentries, ones from |
| 139 | + the scientific ecosystem, Dr.Chuck, Chicago[???], etc. The Carpentries have done a |
| 140 | + great job in the past decade coming up with learning-theory-based tutorials: |
| 141 | + <https://carpentries.org/community-lessons/> |
| 142 | + - [Mariatta] So what do we do next? |
| 143 | + - [Carol] 2 steps: talk about it as EB, but also reach out to Tania & the community |
| 144 | + success project, so there's no duplication of effort. In an ideal world, this |
| 145 | + would be part of the python.org website, design-wise. |
| 146 | + - [Trey] The PSF is trying to answer the question of how do we get more people |
| 147 | + on-boarded with Python, this looks like the answer to that. |
| 148 | + - [Mariatta] I want to make sure that as folks contribute to this, they feel like |
| 149 | + they're collaborating on creating a core piece of Python as opposed to simply |
| 150 | + contributing to a third party platform like Udemy. |
| 151 | + - [Melissa] In 2020, we started building our own documentation, and the person who |
| 152 | + was our first contributor is also now in charge of the docs four years later. |
| 153 | + - [Petr] Recognition is required in some form or another. Contributors will seek it |
| 154 | + out whether we provide it or not. |
| 155 | + - [Ned] If we have new people coming in, I don't think it will be controversial to |
| 156 | + have them start contributing elsewhere and maybe eventually moving to the core |
| 157 | + developer team. |
| 158 | + - [Petr] How much will the communities mingle? The core developers and the |
| 159 | + documentation groups have mostly been separate, and will they work together? They |
| 160 | + need to talk to each other, otherwise there will be trust issues. Perhaps separate |
| 161 | + groups and their own governance is the right way to go. |
| 162 | + - [Mariatta] Let's say there's a large change added — how do we communicate between |
| 163 | + documentation and core devs that a matching tutorial has been created for this new |
| 164 | + change? |
| 165 | + - [Petr] There should be a flag on the PEP saying that the documentation group can |
| 166 | + appropriately present the change in the docs. |
| 167 | + |
| 168 | +## Next meeting |
| 169 | + |
| 170 | +The docs team generally meets on the first Tuesday of every month around 19:00-ish UTC. |
| 171 | + |
| 172 | +We have a recurring Google Calendar event for the meeting. Let Mariatta know your email |
| 173 | +address and she can invite you. |
0 commit comments