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

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.