Documentation Community Team Meeting (July 2022)#
Time: [21:00 UTC]
This HackMD: https://hackmd.io/@encukou/pydocswg1
Discourse thread: https://discuss.python.org/t/16317
Calendar for future meetings: (send your e-mail to Mariatta for a calendar invitation)
How to participate:
Join the Python Docs discord: https://discord.gg/sMWqvzXvde
Use the “General Voice” channel (it does video)
To bring up the side chat: click in the “speech balloon” in General Voice (on Web/desktop, hover over “General Voice” in the side bar to see it)
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!
Adam Turner /
Petr Viktorin /
C.A.M. Gerlach /
Pradyun Gedam /
Hugo van Kemenade /
Jim DeLaHunt /
Ezio Melotti /
Quick updates - Introductions#
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.
Workshops extremely popular so far (Maybe @Mariatta wants to talk more)
Structured param syntax for sqlite3.connect and logging.Formatter
Diataxis and docs changes with Erlend
Continuing PEP migration to PyPA
Next and hopefully last revision of PEP 639 is up
Documenting deprecations in What’s New https://docs.python.org/3.12/whatsnew/3.12.html#deprecated
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.
Diátaxis workshop has a date & signup form:
Dates: 16 Aug (pt. 1) & 18 Aug (pt. 2), both 4pm-6pm UTC
Past Action Items#
[ ] CAM: Carol (and CAM?) will be updating the readme and guide at the sprints.
Update: CAM didn’t see any reviews or feedback on his PRs. (He did take some time off from Python work.)
CAM: Petr ended up more or less doing this first, so I think we can check this off
[x] Adam: Creating a ‘docs-approved’ (wording to be agreed) label for CPython.
Created as the
[x] Petr: Start the Docs WG → Editorial Board rename
[x] Petr: Solicit agenda items on Discourse for the next/future meetings
[x] Petr: Create a
proofreadersteam (Initially: CAM, Adam, Pradyun, Hugo), post about this team on Discourse for a wider audience
[ ] Ezio: Add a “what’s new” section to the devguide (key/important changes)
Should we use blurb?
start simple, then move to blurb if needed
Waiting for the devguide reorg
[ ] Ezio: Add a (How-To) Guides section to devguide
Waiting for the reorg and still thinking about the best way to approach this :thinking_face:
[x] Mariatta: to work with Daniele to organize Diátaxis workshop, CAM & Ned to help with logistics.
For and about the Community or Working Group
Many people signing up (currently oversubscribed), Mariatta will need to pick who can attend
Python Project Documentation#
Writing Diataxis guidelines
how to approach diataxification
internal reorg, doc splitting, etc.
making sections recognizable for readers and writers
naming conventions for sections
naming conventions for anchors
global summary page/table
bunch-of-functions modules vs ~frameworks
initial paragraph with links vs ToC vs list of sections
howtos section organization (titles/etc) / examples vs howtos
(Not) breaking URLs
How much do we care?
we should preserve reference links as much as possible. Tutorial/Guide/etc links we can try and preserve the path to the right location through preserving anchors (perhaps in the footer)
Automation to prevent breakage?
Apply data: Is it possible to look at web server logs to see which fragments are most often followed by incoming visitors?
no, anchors aren’t in server logs (unless we use JS tracking)
[ ] Try building automation using the .inv file
Reorganize the devguide in directories
Squash merge or rebase?
Typing PEP migration
Should we apply the
skip newslabel to documentation PRs?
Labels semantics on PRs vs issues (
Need an admin to create Netlify account: https://github.com/python/cpython/pull/92852
Any Other Business#
Advice on getting traction on an idea for improvement, No clear list of permitted keys in “Declaring project metadata” specification #1101.
Switching video call platforms
[ ] Pradyun to pick this up, and share a link with Petr/Mariatta for the Discord / Google Calendar event.
The docs team meets on the first Monday of every month.
We have a recurring Google Calendar event for the meeting. Let Mariatta know your email address and she can invite you.