|
| 1 | +# Documentation Community Team Meeting (1 April 2025) |
| 2 | + |
| 3 | +## Roll call |
| 4 | + |
| 5 | +(Name / `@GitHubUsername` *[/ Discord, if different]*) |
| 6 | + |
| 7 | +- Adam Turner / `@AA-Turner` |
| 8 | +- Blaise Pabon / `@controlpl4n3` |
| 9 | +- Daniele Procida / `@evildmp` |
| 10 | +- Hugo van Kemenade / `@hugovk` |
| 11 | +- Jeff Jacobson |
| 12 | +- Keith / `@KeithTheEE` |
| 13 | +- Ned Batchelder / `@nedbat` |
| 14 | +- Ryan Duve / `@ryan-duve` |
| 15 | +- Stan Ulbrych / `@StanFromIreland` |
| 16 | + |
| 17 | + |
| 18 | + |
| 19 | +## Introductions |
| 20 | + |
| 21 | +> If there are any new people, we should do a round of introductions. |
| 22 | +
|
| 23 | + |
| 24 | +## Reports and celebrations |
| 25 | + |
| 26 | +> 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. |
| 27 | +
|
| 28 | +> 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. |
| 29 | +
|
| 30 | +- [Stan] |
| 31 | + |
| 32 | + Python Translations Progress Update |
| 33 | + | Language | 30 days progress | |
| 34 | + | -------- | ------------------ | |
| 35 | + | Brazilian Portuguese | +0.91% | |
| 36 | + | Simplified Chinese | +0.56% | |
| 37 | + | Romanian | +0.30% | |
| 38 | + | Russian | +0.20% | |
| 39 | + | Japanese | +0.16% | |
| 40 | + | Traditional Chinese | +0.09% | |
| 41 | + | Greek | +0.08% | |
| 42 | + |
| 43 | + For reference, the current wordcount of the Docs is: |
| 44 | + 1,524,334. |
| 45 | + |
| 46 | + Source: [index.json as of Apr 1, 16:26](https://github.com/python-docs-translations/dashboard/blob/fed87b1e8bbbb809953e5eeac6ba8f59101c26cd/index.json) |
| 47 | + |
| 48 | +- Petr's work on the grammar documentation is on hold for the moment, but going well. |
| 49 | + |
| 50 | + |
| 51 | +## Discussion |
| 52 | + |
| 53 | +### `python-releases.toml` |
| 54 | + |
| 55 | +- Adam gave a brief overview of a project to collate metadata for all releases of Python since 1.6. |
| 56 | + See [python/peps#4331](https://github.com/python/peps/pull/4331). |
| 57 | + |
| 58 | +### Indonesian translation |
| 59 | + |
| 60 | +- Jeff asked how the Indonesian translation could be reinvigorated, |
| 61 | + as currently there is no activity on repo. What are the next steps? |
| 62 | +- Hugo suggested that Jeff could be the next translation coordinator, in order to make a start with PRs and so on. |
| 63 | + This would be a first step to rebuilding the Indonesian translation team team. |
| 64 | +- Agreed that Jeff will open an issue on the [Editorial Board repo](https://github.com/python/editorial-board) asking to do so and with a summary of this discussion. |
| 65 | + |
| 66 | +### Translation governance |
| 67 | + |
| 68 | +- With the translations, we want to let translators get on with their work, rather than getting in the way. |
| 69 | +- There is a gap of who can approve/manage changes to language coordinators, repo permissions in the Python organisation, etc. |
| 70 | +- General agreement for a light-touch & pragmatic approach to managing language coordinators, |
| 71 | + for example approving any coordinator nominated by a core developer, or a similar policy. |
| 72 | +- Translations fall within the Editorial Board's remit, so they might decide a policy statement. |
| 73 | +- Stan has suggested some changes to PEP 545 on [Discourse](https://discuss.python.org/t/83534) about translation management (dealing with inactive translators), translation quality (mass pushing of poor quality machine translations) and improving methods of finding translators (All currently awaiting SC review) and another [Discourse](https://discuss.python.org/t/75750/3) on switcher requirements (inconclusive), |
| 74 | + but these weren't discussed due to audio problems. |
| 75 | + |
| 76 | +### Ensemble contributor session |
| 77 | + |
| 78 | +- Blaise noted he will host a 90-min ensemble session for intermediate to advanced contributors this Friday, |
| 79 | + as an exercise to get folk used to using Python codebase. |
| 80 | +- The topic will be related to [python/cpython#127833](https://github.com/python/cpython/issues/127833) but there is no rigid agenda. |
| 81 | +- Invitation: <https://calendar.app.google/5hjYyVRSjJN5MwdEA> |
| 82 | + |
| 83 | +### Editorial Board update & documentation audits |
| 84 | + |
| 85 | +- Ned gave a brief update from the Editorial Board. |
| 86 | +- Joanna Jablonski (editor, *Real Python*) and Savannah Ostrowski (core developer) are conducting *documentation audits*. |
| 87 | +- These are a formal approach to assessing gaps in documentation and approaching from disciplined first principles. |
| 88 | +- The pair are planning an audit of the *argparse* docs, with the intent to repeat the process elsewhere in the documentation. |
| 89 | + |
| 90 | +### Potential PR process improvements |
| 91 | + |
| 92 | +- What process changes could we explore to increase velocity of merged docs PRs? |
| 93 | + Ideally 'easy wins' rather than sweeping changes. |
| 94 | +- Should we suggest: |
| 95 | + |
| 96 | + * making a single large PR containing all proposed changes? |
| 97 | + * making many small PRs with individual changes? |
| 98 | + * simply waiting for a reviewer? |
| 99 | + |
| 100 | +- The open documentation PRs are slowly increasing, and now at around 240. |
| 101 | +- Ned notes that a frequent blocker is that a seemingly small change can represent a philosophical decision, which take time to reach consensus on. |
| 102 | + Experienced reviewers can spot these types of change quite quickly. How do we communicate this to new contributors? |
| 103 | +- It is disheartening to have a first PR languish unreviewed, or have 70 comments of back-and-forth debate. |
| 104 | +- Hugo noted the exemplar of the *string examples* PR |
| 105 | + ([python/cpython#119445](https://github.com/python/cpython/pull/119445), |
| 106 | + seeking to add an example snippet to each `str` method. |
| 107 | + This is unreviewable with everything in one PR, but e.g. splitting to many small PRs might help refine the process. |
| 108 | + Just a single change request blocks an entire PR, whereas smaller PRs are easier to merge quickly. |
| 109 | + |
| 110 | +- Perhaps we could experiment with defining a tracker issue and splitting it into small tasks. |
| 111 | + Coordination problems or design decisions can be solved on the tracker issue. |
| 112 | +- Daniele noted that if this got traction, many small atomic changes could be a good approach. |
| 113 | + Each might look banal, but are part of a larger whole, and once the first few are approved, |
| 114 | + the reviewer starts to see patterns, reviewing is very quick, and the review experience is nicer. |
| 115 | +- Many small PRs might look like more overhead, but it's not. |
| 116 | +- Perhaps we could try this with the `str` examples PR? |
| 117 | + |
| 118 | +### Synchronous contributions |
| 119 | + |
| 120 | +- Blaise noted that the experience of the PyCon US sprints was valuable, being able to do work, get stuck, get expert help, and then carry on. |
| 121 | + These settings give the freedom to interrupt and get help from more experienced contributors. |
| 122 | +- Technical writers, such as those in the [*Write the Docs* Slack](https://www.writethedocs.org/slack/), would like to help, but don't know where to begin, and a session like this could help. |
| 123 | +- Are there changes we can make to improve the 'just start writing' experience for technical writers, who aren't necessarily programmers? |
| 124 | + |
| 125 | +### PR templates |
| 126 | + |
| 127 | +- Ned noted that it's worth trying anything that might get more people involved. |
| 128 | +- One problem with the PR template in the CPython repo is that it needs to cover every kind of contribution. |
| 129 | + It's hard to word things in a way that docs people would find interesting. |
| 130 | +- The PEPs repo uses multiple PR templates for different types of changes, perhaps this could be explored in CPython. |
| 131 | +- The feature doesn't work perfectly, it is easy to (accidentally) bypass the template and open a blank PR. |
| 132 | +- Agreed that it is likely still worth experimenting, as even if the text is missed, it can be pointed to after the fact. |
| 133 | + |
| 134 | + |
| 135 | +### Wiki news |
| 136 | + |
| 137 | +- Keith gave a brief update on the Python Wiki. |
| 138 | +- The Python Software Foundation (PSF) board may create a focus group for this work as several people are interested, |
| 139 | + which could mean more resources available, and would not block people doing anything. |
| 140 | +- No other substantive news. |
| 141 | +- The wiki server has been upgraded to a better VM so will hopefully be offline less often. |
| 142 | + |
| 143 | +### Weblate |
| 144 | + |
| 145 | +- Progress is being made on a paid translation platform. |
| 146 | + |
| 147 | +*[Monthly reports archive](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html)* |
| 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