# 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

  - Documenting deprecations in What's New
    [docs.python.org/3.12/whatsnew/3.12.html#deprecated](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.

* Diátaxis workshop has a date & signup form:
  - [Announcement post](https://discuss.python.org/t/17075)
  - [Registration form](https://forms.gle/xQSZJ2Yf4Jjd27wf6)
  - Dates: 16 Aug (pt. 1) & 18 Aug (pt. 2), both 4pm-6pm UTC

## 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.
  - [python/core-workflow#458](https://github.com/python/core-workflow/issues/458)
  - Created as the `@python/proofreaders` team
- [x] Petr: Start the Docs WG → Editorial Board rename
  - [python/docs-community#55](https://github.com/python/docs-community/pull/55)
- [x] Petr: Solicit agenda items on Discourse for the next/future meetings
  - [discuss.python.org/t/16317](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
  - [discuss.python.org/t/16319](https://discuss.python.org/t/16319)
- [ ] Ezio: Add a “what's new” section to the devguide (key/important changes)
  - [python/devguide#885](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.
  - [discuss.python.org/t/announcing-the-diataxis-documentation-workshop/17075](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
  * [python/devguide#901](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?
  * [Discussion in Bedevere's tracker](https://github.com/python/bedevere/issues/457).
  * PR: [python/bedevere#485](https://github.com/python/bedevere/pull/485)
  * Labels semantics on PRs vs issues (`stdlib`/`tests`/`docs`/etc.)
  * not blocked
* Need an admin to create Netlify account: [python/cpython#92852](https://github.com/python/cpython/pull/92852)


## Any Other Business

 * Jim
     * Advice on getting traction on an idea for improvement, [_No clear list of permitted keys in "Declaring project metadata" specification_ #1101](https://github.com/pypa/packaging.python.org/issues/1101).

 * Switching video call platforms
   * Jitsi?
   * Google Meet?
   * [ ] Pradyun to pick this up, and share a link with Petr/Mariatta for the Discord / Google Calendar event.