|
| 1 | +# Documentation Community Team Meeting (June 2024) |
| 2 | + |
| 3 | +- **Date:** 2024-06-04 |
| 4 | +- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2024-06-04/19:00/Docs%20Meeting) |
| 5 | +- **This HackMD:** [https://hackmd.io/@encukou/pydocswg1](https://hackmd.io/@encukou/pydocswg1) |
| 6 | +- [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-7th-may-2024/52404) (for May) |
| 7 | +- [**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)) |
| 8 | +- **Calendar event:** (send your e-mail to Mariatta for an invitation) |
| 9 | +- **How to participate:** |
| 10 | + - Go to [Google Meet](https://meet.google.com/dii-qrzf-wkw) and ask to be let in. |
| 11 | + - 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). |
| 12 | + |
| 13 | +By participating in this meeting, you are agreeing to abide by and uphold the [PSF Code of Conduct](https://www.python.org/psf/codeofconduct/). |
| 14 | +Please take a second to read through it! |
| 15 | + |
| 16 | + |
| 17 | +## Roll call |
| 18 | + |
| 19 | +(Name / `@GitHubUsername` *[/ Discord, if different]*) |
| 20 | + |
| 21 | +- Petr Viktorin / `@encukou` |
| 22 | +- Eric |
| 23 | +- Hugo van Kemenade / `@hugovk` |
| 24 | +- Ezio / `@ezio-melotti` |
| 25 | +- Adam |
| 26 | +- Carol / `@willingc` |
| 27 | +- Ryan Duve / `@ryan-duve` |
| 28 | +- Bradley Reynolds / `@shenanigansd` |
| 29 | +- Erlend / `@erlend-aasland` |
| 30 | +- Marcus Sherman / `@betteridiot` |
| 31 | + |
| 32 | +## Introductions |
| 33 | + |
| 34 | +> If there are any new people, we should do a round of introductions. |
| 35 | +
|
| 36 | + |
| 37 | + |
| 38 | +## Reports and celebrations |
| 39 | + |
| 40 | +> 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. |
| 41 | +
|
| 42 | +> 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. |
| 43 | +
|
| 44 | +- 🇮🇹 "Benvenuti! Questa è la documentazione di Python 3.12.3." The Python docs are now officially available in Italian! 🚀 [docs.python.org/it/3/](https://docs.python.org/it/3/) |
| 45 | + |
| 46 | + |
| 47 | +## Discussion |
| 48 | + |
| 49 | +- [Hugo] Plausible stats update [python/cpython#119977](https://github.com/python/cpython/pull/119977), |
| 50 | + 2023 trial data: [hugovk/plausible-stats](https://github.com/hugovk/plausible-stats) |
| 51 | + - Julien would like to have this only on the official site, not on local or redistributor builds |
| 52 | + - We could merge the PR right away and then set up an env variable, |
| 53 | + but it would probably be better to merge with this already set up |
| 54 | + |
| 55 | +- [Carol] |
| 56 | + - PyCon Highlights |
| 57 | + - Dinner with cross-section of core devs, educators, and authors |
| 58 | + - Sprint contribute to docs feedback |
| 59 | + - Sprint discussions |
| 60 | + - [Draft Guiding Principles for Documentation](https://drive.google.com/file/d/1elKNdRPTIoNe6EZ4TbS9aquM-RaNDgmc/view) |
| 61 | + - [Draft meeting notes from yesterday](https://docs.google.com/document/d/1NkaA4LMltE_GISN5v52bWfxA_QGcRxw6U3jzwFQ7c_c/edit?usp=sharing) |
| 62 | + - [Editorial Board Repo](https://github.com/python/editorial-board) (share feedback here) |
| 63 | + - Open an issue to ask for a decision |
| 64 | + - Moving docs from Google Drive to the repo for visibility |
| 65 | + - If folks get blocked, opening an issue on the EB repo is a good way to get in touch. |
| 66 | + - The devguide serves the core dev community more than the general docs community. |
| 67 | + We'll want to put guidelines in the docs repo instead. We'll move slow enough to not disrupt the devguide. |
| 68 | + We'll make it accessible to folks who want to contribute more frequently. |
| 69 | + - [Hugo] Yes, the first step in the devguide is to build CPython. Not ideal |
| 70 | + - [Carol] We had folks like Melanie and Shauna go through the guide and take notes. |
| 71 | + We're planning to put the guide on docsguide.python.org; open it up. |
| 72 | + - Feel free to open issues on the EB repo to give Ned notes & feedback. |
| 73 | + |
| 74 | +- Packaging summit: we're serving 2 groups of users with packaging: producers and consumers. |
| 75 | + There was some discussion about user research, to make it easier to install packages etc., |
| 76 | + going through user personas, etc. A “user success” working group is being set up with the PSF. |
| 77 | + - Maybe the crossover with Docs is helping newcomers. |
| 78 | + |
| 79 | +### Python Project Documentation |
| 80 | + |
| 81 | +*Relating to `docs.python.org`, `peps.python.org`, `devguide.python.org`, etc.* |
| 82 | + |
| 83 | +- [Blaise] Shall we move the deprecations and removals content out of the News file? |
| 84 | + [Discourse](https://discuss.python.org/t/streamline-whats-new-by-moving-deprecations-and-removals-out-of-news/53997) |
| 85 | + - pytest has separate pages for deprecations |
| 86 | + - CAM is working on automating some of this |
| 87 | + - As a user, I'm looking at what's changing now and what's planned to change, so I can plan easily. |
| 88 | + How do I find that easily? |
| 89 | + - Is it possible to *include* all of these from a single source, and still show it in all the What's new documents? |
| 90 | + - [Hugo] Might have a go at this at some point |
| 91 | + - [Eric] I've always appreciated the structure of the What's New |
| 92 | + |
| 93 | +* Parameter annotations: `int | float` or `int or float`? |
| 94 | + |
| 95 | + [discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196](https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196) |
| 96 | + |
| 97 | + - [Erlend] My suggestion is spelling things with words. |
| 98 | + Very often the types aren't formal type hints, so in makes sense to spell “or” |
| 99 | + rather than use the `|` notation. |
| 100 | + - [Hugo] You could always ask the Editorial Board |
| 101 | + - [Carol] Guido will probably have the strongest opinion, |
| 102 | + but he might be out of reach for some time. |
| 103 | + - [Adam] We should ground ourselves in user experience. |
| 104 | + For newcomers arcane language is a barrier. |
| 105 | + If we're already on the edge we should prioritize beginners. |
| 106 | + |
| 107 | + - But we should also make things better for experienced devs -- |
| 108 | + namely, make the reference docs accurate. |
| 109 | + |
| 110 | + - [Adam] Reference docs must be accurate, |
| 111 | + or overall trust in documentation will decline. |
| 112 | + |
| 113 | +* [Eric] The 3 personas are good, but there are others: |
| 114 | + scientists who don't want to become programmers, etc. |
| 115 | + Are there any plans to support these groups? |
| 116 | + - [Carol] I view that as additional axis to split the user base. |
| 117 | + We discussed this, but aren't sure how to language this yet, |
| 118 | + other than just mention it. |
| 119 | + |
| 120 | +* [Hugo] Read the Docs migration |
| 121 | + - we found a few bugs in RTD, some have been fixed, |
| 122 | + we should be good to continue. |
| 123 | + |
| 124 | +* Packaging user docs |
| 125 | + - not in the purview of the Docs EB |
| 126 | + |
| 127 | +* [Marcus] From an instructional standpoint, |
| 128 | + the EB guiding principles are very comforting. |
| 129 | + People jumping into programming from e.g. Excel struggle with e.g. `logging`. |
| 130 | + It's great that we're now focusing more on editorial issues instead of just |
| 131 | + the infrastructure. |
| 132 | + |
| 133 | +* [Ryan] Should we put examples in docstrings? They are very helpful |
| 134 | + - [Hugo] We've historically intentionally kept docstrings shorter. |
| 135 | + The Python documentation is duplicated -- |
| 136 | + both in the docstrings and the main docs. |
| 137 | + - [Ezio] Docstrings should just serve as quick reminders, |
| 138 | + they are not supposed to be exhaustive. |
| 139 | + - [Carol] Some of my thoughts are framed from Jupyter & intellisense experience. |
| 140 | + Historically, info under hover came from the docstrings. |
| 141 | + It's not the only possible source. |
| 142 | + Guido was against docstrings being in scope for the EB. |
| 143 | + There might be ways to get the docs info into the interactive help. |
| 144 | + - [Adam] I emphasize with the desire to keep docstrings shorter. |
| 145 | + I notice that if you open `re`, there's a link to the docs but if you |
| 146 | + do `help(re.search)` it's just the signature and some info. |
| 147 | + Maybe we should add more links to enhance discoverability and reduce duplication. |
| 148 | + |
| 149 | + |
| 150 | +## Next meeting |
| 151 | + |
| 152 | +The docs team generally meets on the first Tuesday of every month around 19:00-ish UTC. |
| 153 | + |
| 154 | +We have a recurring Google Calendar event for the meeting. |
| 155 | +Let Mariatta know your email address and she can invite you. |
0 commit comments