|
| 1 | +# Documentation Community Team Meeting (August 2024) |
| 2 | + |
| 3 | +- **Date:** 2024-08-06 |
| 4 | +- **Time:** [19:00 UTC](https://arewemeetingyet.com/UTC/2024-08-06/19:00/Docs%20Meeting) |
| 5 | +- **This HackMD:** <https://hackmd.io/@encukou/pydocswg1> |
| 6 | +- [**Discourse thread**](https://discuss.python.org/t/documentation-community-meeting-tuesday-6th-august-2024/59599) (for August) |
| 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). |
| 12 | + You need to log in (e.g. with a GitHub account). |
| 13 | + |
| 14 | +By participating in this meeting, you are agreeing to abide by and uphold the [PSF Code of Conduct](https://www.python.org/psf/codeofconduct/). |
| 15 | +Please take a second to read through it! |
| 16 | + |
| 17 | +## Roll call |
| 18 | + |
| 19 | +(Name / `@GitHubUsername` *[/ Discord, if different]*) |
| 20 | + |
| 21 | +- Hugo van Kemenade / `@hugovk` |
| 22 | +- Ezio Melotti / `@ezio-melotti` |
| 23 | +- Trey / `@treyhunner` |
| 24 | +- Manuel / `@humitos` |
| 25 | +- Ned Batchelder / `@nedbat` |
| 26 | +- Petr Viktorin / `@encukou` |
| 27 | +- Usman |
| 28 | +- Carol / `@willingc` |
| 29 | +- Daniele / `@EvilDMP` |
| 30 | + |
| 31 | +## Reports and celebrations |
| 32 | + |
| 33 | +- [Manuel] Moving the docs to Read the Docs |
| 34 | + - Several reasons: be more open (let everyone see if the builds failed, how the builds work); faster builds; |
| 35 | + - A test is already working for pull requests. Only PRs that touch documentation are built. |
| 36 | + - Test: <https://cpython-previews.readthedocs.io/en/main/> |
| 37 | + - [python/docs-community#5](https://github.com/python/docs-community/issues/5) |
| 38 | + - In the last 1-2 months, we've been working on the language and version selector. In the current process this is added at build time from a JSON file, RTD does that at serve time with Javascript so even old versions of the docs link to current versions. |
| 39 | + - We've been working to not losing what we already have but also not get rid of RTD features. |
| 40 | + - 3.13 or 3.14 is the version we'll migrate first, to get a feel for the workflow. All other versions will be served by python.org for now. Then we'll migrate one version at a time. |
| 41 | + - [Trey] Will this enhance the search? [Manuel] There have been many improvements in RTD search lately. Traditionally RTD overwrites Sphinx search entirely with server-side (Elastic Search) search. Now there's a way to choose RTD or Sphinx search from the docs theme. There's also a person who said they're working on the Sphinx sphinx search engine. |
| 42 | + - [Trey] So there won't be a change on day one. |
| 43 | + - [Carol] For the PR previews, is there an option to link to the most changed file in the PR? [Manuel] We're working on it, don't know the details. The idea is to perform a diff and determine what changed, and link to it directly. |
| 44 | + - Issue: [readthedocs/readthedocs.org#11319](https://github.com/readthedocs/readthedocs.org/issues/11319) |
| 45 | + - Design doc: [readthedocs/readthedocs.org#11507](https://github.com/readthedocs/readthedocs.org/pull/11507) |
| 46 | + - [Carol] That's way further ahead than I thought. Thank you! |
| 47 | + |
| 48 | +## Discussion |
| 49 | + |
| 50 | +[Ezio] Deprecations in the What's New file - replacing the list of deprecations with a table |
| 51 | +- [Hugo] We previously talked about putting deprecations in include files. We have that now: <https://docs.python.org/3/deprecations/index.html> |
| 52 | +- Compare <https://pillow.readthedocs.io/en/stable/deprecations.html> and <https://docs.pytest.org/en/stable/deprecations.html> |
| 53 | +- *Some notes compiled after the meeting:* |
| 54 | + - improving deprecation notes: explain how to replace the deprecated API, either in the note, or in a section at the bottom of the module's doc |
| 55 | + - duplication: ensure that the deprecation notes only exist in a single place without duplication (links to it and includes in multiple places are fine) |
| 56 | + - discoverability: making sure that people can easily find what is being deprecated and removed, and how to fix it |
| 57 | + - future-proofing: make sure these info are not completely removed from the latest docs (a link to older versions is fine) |
| 58 | + - layout: list vs table (see [python/cpython#122652](https://github.com/python/cpython/issues/122652)), next step is to create a table as a proof of concept to see what works best |
| 59 | +- *Some additional links:* |
| 60 | + - python-dev thread from a decade ago: <https://mail.python.org/pipermail/python-dev/2011-October/114199.html> (some of these things are fixed, some are no longer relevant, some still need work) |
| 61 | + - Enforcing the use of deprecated-removed: [python/cpython#92564](https://github.com/python/cpython/issues/92564) |
| 62 | + - A related core-workflow issue: [python/core-workflow#468](https://github.com/python/core-workflow/issues/468) |
| 63 | + - Moving deprecations into include files: [python/cpython#122085](https://github.com/python/cpython/issues/122085) |
| 64 | +- Next step: add a demo of how the table would look |
| 65 | + |
| 66 | +[Ezio] Defining and documenting a procedure to ensure that we follow up on additional tasks brought up in review |
| 67 | +- [python/devguide#1359](https://github.com/python/devguide/issues/1359) |
| 68 | +- [Hugo] If someone says “let's do this”, they should be in charge of who's going to do it |
| 69 | +- [Ezio] There's a “diffusion of responsibility”, we should define who should go and open the issue to follow up. The proposal is that the PR author should be in charge -- either volunteer to follow up or find other actors to do it. |
| 70 | +- [Carol] One thing we've done on other projects is that the person who proposes additional work should open that issue; then it's fair game for anyone to pick it up. |
| 71 | +- [Ezio] One reason I mentioned the author of the PR is that someone could come and see an issue, but they don't have the context that the PR author has. |
| 72 | + |
| 73 | +[#118891 Slow actions for doc builds](https://github.com/python/cpython/issues/118891) |
| 74 | + |
| 75 | +### PEP Workflow |
| 76 | + |
| 77 | +- [PEP 750: Tag strings for writing domain specific languages](https://github.com/python/peps/pull/3858) FYI |
| 78 | + |
| 79 | +## Follow-ups from previous meeting(s) |
| 80 | + |
| 81 | +*[Monthly reports archive](https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html)* |
| 82 | + |
| 83 | +## Next meeting |
| 84 | + |
| 85 | +The docs team generally meets on the first Tuesday of every month around 19:00-ish UTC. |
| 86 | + |
| 87 | +We have a recurring Google Calendar event for the meeting. |
| 88 | +Let Mariatta know your email address and she can invite you. |
0 commit comments