Documentation Community Team Meeting (July 2022)#

  • Date: 2022-07-11

  • Time: [21:00 UTC]

  • This HackMD: https://hackmd.io/@encukou/pydocswg1

  • Discourse thread: https://discuss.python.org/t/16317

  • Calendar for future meetings: (send your e-mail to Mariatta for a calendar invitation)

  • How to participate:

    • Join the Python Docs discord: https://discord.gg/sMWqvzXvde

    • Use the “General Voice” channel (it does video)

    • To bring up the side chat: click in the “speech balloon” in General Voice (on Web/desktop, hover over “General Voice” in the side bar to see it)

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

  • Petr Viktorin / @encukou

  • C.A.M. Gerlach / @CAM-Gerlach

  • Pradyun Gedam / @pradyunsg

  • Hugo van Kemenade / @hugovk

  • Jim DeLaHunt / @JDLH

  • Ezio Melotti / @ezio-melotti

  • Guido / @gvanrossum

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.

  • CAM

    • Workshops extremely popular so far (Maybe @Mariatta wants to talk more)

    • Structured param syntax for sqlite3.connect and logging.Formatter

    • Diataxis and docs changes with Erlend

    • Continuing PEP migration to PyPA

    • Devguide reorg

    • Next and hopefully last revision of PEP 639 is up

  • Hugo

    • Documenting deprecations in What’s New https://docs.python.org/3.12/whatsnew/3.12.html#deprecated

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#

Past Action Items#

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

    • CAM: Petr ended up more or less doing this first, so I think we can check this off

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

    • https://github.com/python/core-workflow/issues/458

    • Created as the @python/proofreaders team

  • [x] Petr: Start the Docs WG → Editorial Board rename

    • https://github.com/python/docs-community/pull/55

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

    • https://discuss.python.org/t/16317

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

    • https://discuss.python.org/t/16319

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

    • https://github.com/python/devguide/issues/885

    • Should we use blurb?

      • start simple, then move to blurb if needed

    • Waiting for the devguide reorg

  • [ ] Ezio: Add a (How-To) Guides section to devguide

    • Waiting for the reorg and still thinking about the best way to approach this :thinking_face:

  • [x] Mariatta: to work with Daniele to organize Diátaxis workshop, CAM & Ned to help with logistics.

    • https://discuss.python.org/t/announcing-the-diataxis-documentation-workshop/17075

‘Internal’ items#

For and about the Community or Working Group

None

Diataxis Workshop#

  • Many people signing up (currently oversubscribed), Mariatta will need to pick who can attend

Python Project Documentation#

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

  • Writing Diataxis guidelines

    • how to approach diataxification

      • internal reorg, doc splitting, etc.

    • making sections recognizable for readers and writers

      • explicit boxes/directives

      • naming conventions for sections

      • naming conventions for anchors

        • (i.e. .. _<module>-guide:; .. _<module>-reference:)

        • global summary page/table

    • bunch-of-functions modules vs ~frameworks

    • page structure

      • initial paragraph with links vs ToC vs list of sections

      • howtos section organization (titles/etc) / examples vs howtos

  • (Not) breaking URLs

    • How much do we care?

      • we should preserve reference links as much as possible. Tutorial/Guide/etc links we can try and preserve the path to the right location through preserving anchors (perhaps in the footer)

    • Automation to prevent breakage?

      • Apply data: Is it possible to look at web server logs to see which fragments are most often followed by incoming visitors?

        • no, anchors aren’t in server logs (unless we use JS tracking)

      • [ ] Try building automation using the .inv file

  • Reorganize the devguide in directories

    • https://github.com/python/devguide/pull/901

    • Squash merge or rebase?

      • rebase

  • Typing PEP migration

Workflow#

  • Should we apply the skip news label to documentation PRs?

  • Need an admin to create Netlify account: https://github.com/python/cpython/pull/92852

Any Other Business#

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.