Documentation Community’s Team Meeting (March 2022)#

  • Date: 2022-03-07

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

Roll call#

  • name / affiliation / @github-username

  • Petr / RedHat, SC / @encukou

  • Mariatta / Core Dev / @mariatta

  • Pradyun / ??? / @pradyunsg

  • CAM / NASA, PEP infra team / @CAM-Gerlach

  • James Gerity / random user / @SnoopJeDi

  • Julien Palard / Core Dev / @JulienPalard

  • Ned / Community member /

  • Adam / nil / @AA-Turner

Quick updates - Introductions#

  • Julien https://github.com/sphinx-contrib/sphinx-lint

    • 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

Agenda items#

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 docs-community and/or python-dev to 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?

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

[We didn’t get to this]

Docs WG Docs#

[We didn’t get to this]

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. 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

Next meeting#

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.