Documentation Community Team Meeting (May 2022)#
Date: 2022-05-02
Time: 21:00 UTC (!! one hour earlier due to daylight savings, speak up if this is a problem !!)
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-usernameMariatta /
@mariattaCarol /
@willingcAdam T /
@AA-TurnerNed Batchelder /
@nedbatFred Drake /
@freddrakeCAM Gerlach /
@CAM-GerlachJelle /
@JelleZijlstraGuido van Rossum /
@gvanrossumPradyun Gedam /
@pradyunsg
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.
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.
PyCon happened!
A new docs triager (Shantanu; @slateny)
Agenda items#
‘Internal’ items#
For and about the Community or Working Group
The vision of Docs WG (with Carol Willing)#
In Carol’s absence, there was some misunderstanding. We weren’t meant to be a PSF working group. It was meant to be a Python Steering Council working group, which happened to use the PSF code of conduct.
There are two groups: the Docs WG and the Docs Community team.
Anyone can join the community team, and have a sense of community. That’s what this meeting has been.
The Working Group was focused on a smaller set of people with two purposes:
function as an editorial board, help make decisions when the community couldn’t find consensus on a docs/content issue.
To set the vision for where docs should go long-term. Specifically, what docs need to be written. For example, new parts of docs, new audiences for docs, etc.
Carol, Mariatta, Ned, Julien, wrote the charter, it was approved by the Steering Council. Next step is to define how to onboard new members and how we would sustain the group going forward. We haven’t done that step yet. It could be done similar to how the diversity PSF group is doing it. Interested people would contact an existing member, the group would discuss if the person has been active. If so, they would be invited to join. Otherwise, they could join the Docs Community and re-apply later.
The original presentation to the language summit is online, and there’s a blog post from the summit.
CAM: I’m confused because the readme said PSF working group. A lot of the discussions have been based on the readme.
The work we’ve been doing was fine as a community group. Do we need to be a formal working group?
Carol: Some people felt that parts of the docs were “theirs”, and they could dictate what happened to those pages. We felt all the docs were a community resource. Personally owned docs belong on personally owned sites.
Carol: In a perfect world, a community team would be enough. But if the community can’t resolve a conflict, the working group could resolve it. The working group could provide more coordination where needed (alignment between CPython docs and the PSF web site as a whole).
Adam: do we need anything between the community and the steering council? Is the middle group (docs wg) moot? Carol: the docs wg could be very lightweight: resolve conflicts, take recommendations from the community.
Carol: we don’t want to wholesale restructure the docs. instead, supplement what we have and incrementally change what we have.
This group shouldn’t discuss working group mechanics.
CAM: To reduce confusion: if the main point of the WG is to be the editorial board, maybe a new name would make it clearer.
Guido: renaming could be a good idea. Let the WG form their own meeting schedule. Petr was saying he didn’t want to be on the WG, he wanted to be in the Docs community. Petr proposed using diataxis, which doesn’t recommend large-scale restructuring, so it’s in line with Carol’s recommendations also.
Lightweight governance is best.
[ ] Carol (and CAM?) will be updating the readme and guide at the sprints.
If we rename the WG to an Editorial Board, we should clarify the interpretation of the name.
A quarterly meeting for the WG seems like the right cadence.
Editorial Board is the agreed name. Wikipedia has a good definition which aligns with our meaning.
Python Project Documentation#
Relating to docs.python.org, peps.python.org, devguide.python.org, &c.
Style Guide#
Ned: Would like to have a clearer single voice, instead of pages having disparate content types in terms of reference, examples, narrative style etc. Consistency on “tone of voice” (neutral “the”, plural “we”), structuring of invidiual pages, is somewhat lacking. Discussing or deciding on a single “house style” for documentation pages may be a useful thing to do to produce a reference.
Guido: A north star document would be useful, but he sees a risk of “PEP 8” like changes – mechanical edits to the text without substantive improvements
Carol: There is a style guide in the DevGuide, although very dated. Mariatta thinks it should be held somewhere that isn’t the DevGuide, (didn’t catch where?).
There’s a current style guide in the devguide – we should review this one and check what (if anything) we should improve and update.
[ ] Anyone can make pull requests to update the devguide. Carol & Mariatta can review pull requests.
Improving documentation PR review#
Ned: Concept of Documentation-focused committers? A pool of people who can merge Docs PRs. The Jupyter team set out guidance for when documentation should be changed. For now we should focus on substantive changes whilst we have fewer committers focussed on docs.
Adam: can we have a team of people who are “approved” to review docs changes? Improving the reviewing story for docs, so that core devs can use it as a signal that someone trustworthy has given a +1 to the change.
[x] Mariatta will open a ticket to give Ned, CAM, Pradyun, and Adam triage permissions for CPython.
We should also communicate that the volume of PRs will (hopefully!) increase, so reviewing every single PR is not needed. Advertising the docs community is also a public good.
Miscellaneous#
Mariatta: Documentation teams should be involved in the Python development cycle in terms of documenting new features, changes, improvements.
Carol: Start small and increase – what two or three things do we want to do now?
Ned: Revisit concern about churn of documentation in terms of PRs – for documentation changes, style changes (may) be real improvements, as the million people are impacted by better style and clarity, rather than the ~100 who read the actual CPython code.
Issue triage#
Issues in the docs-community repo: many are requests to review docs-oriented bpos. We won’t do this anymore. Instead, we can follow a label in the CPython repo.
AOB#
None
Next meeting#
The docs team meets on the first Monday of every 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.