Documentation Community Team Meeting (August 2023)#

  • Date: 2023-08-01

  • Time: 19:00 UTC

  • This HackMD: https://hackmd.io/@encukou/pydocswg1

  • Discourse thread (for August)

  • Meeting reports (the latest one might be an unmerged PR)

  • Calendar event: (send your e-mail to Mariatta for an invitation)

  • How to participate:

    • Go to Google Meet and ask to be let in.

    • To edit notes, click the “pencil” or “split view” button on the HackMD document. 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. Please take a second to read through it!

Roll call#

(Name / @GitHubUsername / Discord if different)

  • Hugo van Kemenade / @hugovk

  • Daniele Procida

  • Manuel Kaufmann / @humitos

  • Ryan Duve / @ryan-duve

  • C.A.M. Gerlach / @CAM-Gerlach

  • Petr Viktorin / @encukou

  • Marcus Sherman / @betteridiot

  • Joe Kaufeld / @itsthejoker

Reports and celebrations#

  • PR to keep “translated” attribute on translated nodes landed and released! :tada:

    • https://github.com/python/docsbuild-scripts/issues/148#issuecomment-1648836409 has the details on how it’s exposed!

  • [Hugo] CPython sprint at EuroPython: we had one room for code and another for documentation, and merged some 140 PRs in total! Thanks to Daniele for helping out and all the excellent docs advice! (Photos: https://mastodon.social/@hugovk/110792652209141428)

Discussion#

  • Should we set up Trusted Publishers on python-docs-theme?

    • Pradyun will file an issue

  • [Hugo] Plausible trial update

    • Public Dashboard [link expired]

    • Would be too expensive to pay for hosted version

    • Should be easy to host it ourselves on PSF infra

    • Next step:

      • Ask PSF/Ee if we want to self-host, or pay for the service (or get sponsored)

      • Let the SC look at the dashboard

  • [Hugo] Dark theme deploy: 3.11 RM Pablo said fine to deploy. To deploy, need to merge python/docsbuild-scripts#161 and/or pin in requirements.txt

  • [CAM] Update on structured deprecation work

    • Originaly prompted by a recent Discourse thread on soft deprecations

    • Went through many iterations of design and testing on examples

    • Wrote up a detailed design doc with:

      • Rationale and benefits

      • Phased implementation plan

      • Directive input schema

      • JSON, etc. output schema

      • Worked through examples

      • Open questions and additional notes

    • Initial implementation currently in progress; should have a final

  • [Daniele] On-going documentation commit approaches

    • suggest changing approach to docs PRs

      • Often a PR will make docs look worse – highlight what needs to be changed

      • docs no longer need to target only “graybeards”, but also many new “non-programmers”

    • [CAM] Maybe also discussion of the Porting Guide PR as an application of this?

    • Maybe mark documents as historical?

    • Forward plan: Merge Daniele’s PR and open an issue for a followup to remove/update more outdated content

Next meeting#

The docs team generally meets on the first Tuesday of every month.

We have a recurring Google Calendar event for the meeting. Let Mariatta know your email address and she can invite you.