Documentation Community Team Meeting (July 11, 2022)

Roll call

(Name / @GitHubUsername)

  • 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

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.

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

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

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

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

    • python/devguide#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.

‘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

  • Typing PEP migration

Workflow

Any Other Business