Documentation Community Team Meeting (July 2022)¶
Date: 2022-07-11
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!
Roll call¶
name /
@github-username
Adam Turner /
@AA-Turner
Petr Viktorin /
@encukou
C.A.M. Gerlach /
@CAM-Gerlach
Pradyun Gedam /
@pradyunsg
Hugo van Kemenade /
@hugovk
Jim DeLaHunt /
@JDLH
Ezio Melotti /
@ezio-melotti
Guido /
@gvanrossum
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.
CAM
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
Devguide reorg
Next and hopefully last revision of PEP 639 is up
Hugo
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
Agenda items¶
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.
https://github.com/python/core-workflow/issues/458
Created as the
@python/proofreaders
team
[x] Petr: Start the Docs WG → Editorial Board rename
https://github.com/python/docs-community/pull/55
[x] Petr: Solicit agenda items on Discourse for the next/future meetings
https://discuss.python.org/t/16317
[x] Petr: Create a
proofreaders
team (Initially: CAM, Adam, Pradyun, Hugo), post about this team on Discourse for a wider audiencehttps://discuss.python.org/t/16319
[ ] Ezio: Add a “what’s new” section to the devguide (key/important changes)
https://github.com/python/devguide/issues/885
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.
https://discuss.python.org/t/announcing-the-diataxis-documentation-workshop/17075
‘Internal’ items¶
For and about the Community or Working Group
None
Diataxis Workshop¶
Many people signing up (currently oversubscribed), Mariatta will need to pick who can attend
Python Project Documentation¶
Relating to docs.python.org
, peps.python.org
, devguide.python.org
, &c.
Writing Diataxis guidelines
how to approach diataxification
internal reorg, doc splitting, etc.
making sections recognizable for readers and writers
explicit boxes/directives
naming conventions for sections
naming conventions for anchors
(i.e.
.. _<module>-guide:
;.. _<module>-reference:
)global summary page/table
bunch-of-functions modules vs ~frameworks
page structure
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
https://github.com/python/devguide/pull/901
Squash merge or rebase?
rebase
Typing PEP migration
Workflow¶
Should we apply the
skip news
label to documentation PRs?PR: https://github.com/python/bedevere/pull/485
Labels semantics on PRs vs issues (
stdlib
/tests
/docs
/etc.)not blocked
Need an admin to create Netlify account: https://github.com/python/cpython/pull/92852
Any Other Business¶
Jim
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
Jitsi?
Google Meet?
[ ] Pradyun to pick this up, and share a link with Petr/Mariatta for the Discord / Google Calendar event.
Next meeting¶
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.