Documentation Community Team Meeting (December 2022)

• Date: 2022-12-05

• Time: 20:00 UTC

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

• Discourse thread

• 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

• Mariatta / @mariatta

• Petr / @encukou

• Ezio / @ezio-melotti

• Hugo van Kemenade / @hugovk

• CAM / @CAM-Gerlach

• Jim DeLaHunt / @JDLH

Reports and celebrations

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.

• Hugo’s promotion to Core Developer! 🎊

• @JDLH: A [packaging] docs issue I filed has been fixed, I feel like I made a (small) contribution. No clear list of permitted keys in “Declaring project metadata” specification issue #1101, fixed by Brett Cannon in PR #1168.

Discussion

Python Project Documentation

Relating to docs.python.org, peps.python.org, devguide.python.org, &c.

• (Hugo) Add release cycle chart to docs:

  • CSV PR was merged

  • charts PR ready for review -> merged during the meeting :rocket:

  • demo

  • Followup: @CAM-Gerlach opened devguide issues for adding the additional development phase transition dates python/devguide#998 & a table of individual minor versions python/devguide#999

  • Followup: Hugo will check with it no JavaScript, and the remote hosting of https://unpkg.com/mermaid/dist/mermaid.min.js in case it goes down

    • -> No JS PR: https://github.com/python/devguide/pull/997

• https://packaging.python.org/en/latest/glossary/

  • @CAM-Gerlach to improve the glossary. It can then be linked or copied to CPython docs.

PEP Workflow

• PEP 1 rewrite?

  • It was generally agreed that PEP 1 (and PEP 12) could use significant re-organization and trimming.

  • Petr suggests moving the author-facing help out of PEP 1/to the devguide

  • CAM mentions python/peps#2337 which proposes referencing the Sphinx reST primer instead of duplicating information there in PEP 12 and consolidating normative process guidance in PEP 1 and author-facing info in PEP 12/the devguide

  • @CAM-Gerlach will open a PR implementing that first step, linking the Sphinx reST primer in PEP 12 instead of duplicating that information

  • CAM also mentions the devguide’s reST primer is essentially just a less-up-to-date copy of the Sphinx one; it should be revised to link to it and focus on CPython-specific guidance. This issue was already open as python/docs-community#57, which was moved to python/devguide#1000, where @CAM-Gerlach will work on it

• Final PEPs and the canonical docs banner link

  • python/peps#2719 will improve the existing banners directing users to the canonical docs for Final PEPs added in python/peps#2702 to be sticky at the top; @CAM-Gerlach to submit PR

  • We can start going through Final PEPs and systemically marking them with the new banner as appropriate

  • @CAM-Gerlach will submit PRs for python/peps#2872 to mark old implemented Accepted PEPs as Final, and will add banner in the process

  • We might need a checklist for marking PEPs Final

    • e.g.: is it documented outside the PEP? Add a note?

  • @CAM-Gerlach will open an issue to discuss adding checklists for new, Approved/Rejected and Final PEPs (opened as python/peps#2937)

• Status for PEP 659?

  • @CAM-Gerlach will open issue proposing a list of obselete PEPs to the SC to be formally rejected

  • We may need an obselete status?

Improve SEO for CPython docs

• (Hugo) OpenGraph metadata PRs:

  • devguide: merged, increases Google’s SEO score 91->100

  • CPython: ready for review, increases Google’s SEO score ~66->91 -> approved during and merged after the meeting :rocket:

  • Followup: tell Marc-André about use of logo without font

  • PEPs: TODO

Next meeting

The docs team meets on the first Monday of every month.

• First Monday of January 2023 is 2 Jan 2023. Will we all be ~~recovered from our New Year’s celebrations~~ back at Python work and ready to meet on that date?

• January 9 2023 instead.

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