Documentation Community’s Team Meeting (March 2022)#
Time: 22:00 UTC
This HackMD: https://hackmd.io/@encukou/pydocswg1
GitHub issue: Agenda Planning Issue
Calendar for future meetings: XXX
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!
name / affiliation /
Petr / RedHat, SC /
Mariatta / Core Dev /
Pradyun / ??? /
CAM / NASA, PEP infra team /
James Gerity / random user /
Julien Palard / Core Dev /
Ned / Community member /
Adam / nil /
Quick updates - Introductions#
fork of the rstlint.py from CPython, as an independent project
Reports and celebrations#
Shout out to @AA-Turner, Barry, Mariatta and everyone who contributed for getting PEP 676 over the finish line! Its a huge improvement both for us PEP editors, and the Python community at large. — CAM
Docs and PEPs#
Is the Docs Community concerned with PEP editing? (Devguide?)
Seems like the PEP editors are more concerned with that, since they are the editorial board and implementation team for PEPs like the Docs WG and Docs Team is for PEPs, though on broader or cross-cutting issues that affect both (e.g. what should be a PEP vs. go elsewhere, harmonizing common standards) then it would be good to involve the latter as well. — CAM
Cross-cutting or broad issues – perhaps the documentation community forum is a good one for collaboration and forming consensus.
Python Language Summit @ PyCon US#
If there’s any updates/issues that would be relevant to the Python core developers, this would be a good place for presenting that for discussion!
Still in planning stage, but worth it to start thinking about it now, if you want to bring up something for discussion.
Petr gave a summary of what the event will look like.
In-person event, at PyCon US 2022.
What would the presentation be about?
Updates, items that need support from core devs
Pay attention to
python-devto fill out a form
We talked about the docs group at the last 2 lang summits. This time the group has started!
Desires for revamping the main CPython documentation theme might be a topic for discussion?
Lightning talk sounds good
Structuring Docs, Devguide, and PEPs#
Some PEPs are turning into long-lived documentations.
Packaging PEPs used to be, moving to packaging.python.org
typing is moving into a similar situation.
__future__page in Python docs is also a list of PEP references.
Helping the typing community move their PEPs into a separate spot.
In the Python documentation? Outside of Python documentation?
There’s an ongoing effort?
Should the typing specifications live in Python docs or externally?
The fact that core developers don’t care strongly about typing documentation isn’t a good reason to keep them external to it.
PEPs are not documentation.
Getting the typing folks to agree that their work needs to be in the Python documentation.
[discussion of what goes in Python docs vs externally]
If a user is reading only the Python docs, is that sufficient information to understand?
PyPA has standards, and uses PEPs as proposals to change the standards
Should we expand the scope of the Python docs?
What’s the scope of this group? Are we advisors, or do we do the work?
Potentially WSGI spec and similar
[We didn’t get to this]
Docs WG Docs#
[We didn’t get to this]
Having a clear and opinionated style guide can enable more contributions. It will clarify expectations, making it easier to create pull requests that will get accepted. It will remove individual ownership of pages, which creates roadblocks to merging. Ned
The style guide could cover questions like:
How to best use code examples
When to use “roughly equivalent” implementations
How to divide different kinds of documentation
First step could be understanding how the current docs align with the diataxis framework
Book suggestion: Docs for Developers
Plan is to meet every month.
Next meeting: April 4th, 22:00 UTC
We have a Google Calendar event for the next meeting, set to recur on the first Monday of each month. Let Mariatta know your email address and she can invite you to the event.