Documentation Community Team Meeting (June 2022)#

  • Date: 2022-06-06

  • 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)

  • How to participate: Use the “General Voice” channel (it does video); hover over “General Voice” in the side bar and click in the “speech balloon” to bring up the side chat

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

  • Guido van Rossum / @gvanrossum

  • Petr Viktorin / @encukou

  • Pradyun Gedam / @pradyunsg

  • Ezio Melotti / @ezio-melotti

  • CAM Gerlach / @CAM-Gerlach

  • Mariatta / @mariatta

  • Ned Batchelder / @nedbat

  • Hugo van Kemenade / @hugovk

  • Mats Wichmann / @mwichmann

  • John P. Rouillard / @rouilj

  • Daniele Procida / @evildmp

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.

  • Daniele is the author of Diátaxis.

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.

  • CPython triage permissions for CAM, Pradyun, Adam, and Ned.

Agenda items#

Past Action Items#

  • [ ] 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.)

  • [ ] Creating a ‘docs-approved’ (wording to be agreed) label for CPython.

Needs discussion, please open issue on core-workflow repo. (There’s a template for label changes: https://github.com/python/core-workflow/issues/new/choose)

‘Internal’ items#

For and about the Community or Working Group

Docs WG renaming to Editorial Board#

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.

Status: There are currently no meetings for the editorial board.

  • [ ] Petr: Do the rename of “working group/WG” to “Editorial Board” in all the docs

Docs governance#

Guido: There may be a need for a bit more leadership within this group/”Community”. Having an organiser for the meetings.

Petr: What does this mean in practice?

Guido: Being in charge of the agenda, how long things are discussed.

Petr: Fine with that, that’s how things work today. Does this need to be formalised somehow?

Guido: Someone should have ‘Convening’ power – someone to take ownership of filling the agenda, managing the admin, etc.

Adam: Typing has more active solicitation of agenda items. That might be a concrete improvement/action item out of this.

Petr: in agreement

CAM: The Documentation category on Discourse serves this role, and we have posts on there for some of these meetings.

Ned: Where are decisions made? Typing-sig makes decisions affecting them, as it is a forum of typing-checker implementers and users. Can Discourse be a place decisions are made?

Ned: There’s agreement about that we should use Diataxis, but not about how we should implement it.

  • [ ] Petr: Solicit agenda items on Discourse, for the next/future meetings

Python Project Documentation#

Relating to docs.python.org, peps.python.org, devguide.python.org, &c.

Proofreaders GitHub team#

It would be useful to have a GitHub team that can be @mentioned in docs PRs to request reviews of the English grammar.

  • [ ] Petr: Create a proofreaders team (Initially: CAM, Adam, Pradyun, Hugo), post about this team on Discourse (or similar) for a wider audience

Devguide improvement plans#

Ezio made some comments in a thread:

The first plan is to overhaul a bit the GitHub docs, and is also related to other changes about labels. The second plan is still somewhat half-baked, but I wanted to

  1. add some instructions about following the development of CPython

Ezio: Add a changelog page to the devguide for an overview of workflow changes

  • [ ] Ezio: Add a “what’s new” section to the devguide (key/important changes)

CAM: Two different types of content: new pages on tools and workflow versus changes to existing policies and proceduces.

Guido: Not that useful to distinguish these, as it adds more categories. Everything is new.

Ned: Is a problem that we have different audiences? E.g. triagers versus developers versus contributors to Python

Guido: The three audiences should be (core devs & triagers), contributors, and redistributors/people who need to build Python.

  1. add a “tips and tricks” page There is some overlapping between https://devguide.python.org/communication/, the instructions that I want to add, the tips and tricks page, and other pages like the GitHub bootcamp though, so I’m still trying to figure out all the things I want to include and then what would be the best way to organize them.

Ned: This sounds like Ezio is suggestion that the devguide should have a ‘how to’ section (one of the four sections of Diataxis).

  • [ ] Ezio: Add a (How-To) Guides section with these

Adopting Diátaxis#

https://discuss.python.org/t/adopting-the-diataxis-framework-for-python-documentation/15072

What’s the next step – survey what we already have, as Ezio suggested?

Daniele: We should consider not only consensus on adopting the framework, but also understanding what it’s about, and how it could be implement it. Best way to do it would be a couple of workshops.

Ned: What’s a workshop?

Daniele: Two 2-hour interactive workshops: theory, interactive exercises, Normally it’s in-person.

Ned: Who’d participate?

Daniele: Up to 30 people. Happy to do it for people who wouldn’t be working on Python itself. Often do it at conferences.

Adam: Who should be in the workshops? Core devs? This group? Docs contributors?

Daniele: People who are pushing this thru, presenting to others. But skills should be spread far. Need enough people to make it sustainable.

We can probably get more people for a workshop than on this meeting.

  • [ ] Mariatta: to work with Daniele to organize the workshop, CAM & Ned to help with logistics.

Workflow#

(not discussed due to time)

Should we apply the skip news label to documentation PRs? Discussion in Bedevere’s tracker.

Speeding up the Docs / Docs CI job – pros and cons.

Any Other Business (AOB)#

None

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.