Documentation Community’s Team Meeting (April 2022)#
Date: 2022-04-04
Time: 21:00 UTC
This HackMD: https://hackmd.io/@encukou/pydocswg1
GitHub issue: Agenda Planning Issue
Calendar for future meetings: (send your e-mail to Mariatta for a calendar invitation)
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
Petr /
@encukou
Mariatta /
@mariatta
Ned /
@nedbat
Fred Drake /
@freddrake
CAM Gerlach /
@CAM-Gerlach
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.
Office hours @BostonPython - choose your own adventure as a way to branch during installation instructions.
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.
Agenda items#
Let’s collect all potential agenda items here before the start of the meeting. We will then attempt to create a coherent agenda that fits in the 60m meeting slot. If there are similar items try and group them together.
PEP 588 – GitHub Issues Migration Plan#
GitHub Issues migration plan
https://github.com/python/peps/issues/2497
We will update PEP 588 with current plan of migration. Don’t create yet another PEP.
Devguide PR: https://github.com/python/devguide/pull/814
[x] Mariatta: reply
Clean up, fix and improve grammar, phrasing, syntax/links and overall prose quality in charter#
Who should review PR29? What’s the official status of the charter?
[ ] Ned: Review the PR
[ ] Mariatta: Review the PR
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.
Signup: https://us.pycon.org/2022/events/language-summit/
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?
https://typing.readthedocs.io/en/latest/
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
Release PEPs?
Issue triage#
I’m not sure this is the best use of everyone’s time on this call but, if we have time: sure, why not! [name=Pradyun] I agree, this seems like in-the-trenches work we can get to after establishing the shape of the effort and group [name=Ned]
For each issue we should decide:
What’s blocking the issue? (Is it a decision the WG should make?)
How can we help move it forward?
Discussion outside the meeting should be on the issues :)
[ ] CAM: Open Sphinx issue to improve indexing ordering and list builtins
Bringing in new people#
When “herding cats”, play into people’s exixting strengths/interests
Give people smaller, manageable tasks.
[ ] Petr: think about how to generate manageable tasks
New WG member?#
CAM would be a good new voting member of the formal WG
OTOH, the formal WG isn’t that important, so figuring out how to get new people into it might not be a good priority
Docs WG Docs#
The group’s docs are incomplete. Should we fill in the blanks? Scrap some pages and focus on docs?
Adding and onboarding new workgroup members https://docs-community.readthedocs.io/en/latest/workgroup/adding-members.html
Milestones and roadmaps https://docs-community.readthedocs.io/en/latest/workgroup/milestones.html
Discussion platform https://docs-community.readthedocs.io/en/latest/community/contributing.html
Discourse, Discord, GH issues, any more?
Documentation Team https://docs-community.readthedocs.io/en/latest/community/team.html
Who should be in the Community team?
Documentation guidance#
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. [name=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
https://documentation.divio.com/
https://diataxis.fr/
First step could be understanding how the current docs align with the diataxis framework
Book suggestion: Docs for Developers
[ ] Petr: Gain consensus on Diataxis framework
Next meeting#
Plan is to meet First Monday of the month.
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.