author:["Mariatta"]

title:"Meeting Minutes: Dec 10, 2024"

date:"2024-12-10"

description:"Meeting Minutes from Python Docs Editorial Board: December 10, 2024"

summary:"Meeting Minutes from Python Docs Editorial Board: December 10, 2024"

tags:["minutes"]

categories:["minutes"]

series:["Meeting Minutes"]

ShowToc:false

TocOpen:false

members:["Guido van Rossum", "Mariatta", "Ned Batchelder"]

* Is what we’re doing fulfilling the purpose of the EB?

* We have been very casual

* We can be more proactive instead of waiting to be asked for a decision.

* Tables vs two-line summary:[https://discord.com/channels/935215565872693329/935215566334079058/1313842986836037683](https://discord.com/channels/935215565872693329/935215566334079058/1313842986836037683)

* Indecisions about docs are blocking contributions

* Diataxis says to make plans and decisions, not sweeping changes

* Log of decisions:

* We have the changelog[https://python.github.io/editorial-board/changelog/](https://python.github.io/editorial-board/changelog/)

* People might want a one-size-fits-all decisions but

* Churns for docs is different with code churns

* Maybe we’d be more open to it?

* We can be more proactive instead of reactive

* Still mention that please don’t make PRs just to make sweeping changes to conform to the new styling decisions

* How to be more proactive: just be more active on the Docs discourse. We can say “the board discussed it and …”

* Docs audit?

* Get more of a plan on how to proceed from Joanna

* Docs needing fixing: Argparse, asyncio, Threading (incl. concurrent.futures)

* Request decision

* Request for decision: how should we mark up types in parameter lists?

* Make it a formal decision:

* Use the word or instead of |

* Instead of | None, use “optional”?

* Use “default” instead of “optional”

* We are moving to Tuesdays

* Next meeting is Tuesday Jan 14

* We should discuss docs issues more instead of personal projects

author:["Mariatta"]

title:"Meeting Minutes: Jan 14, 2025"

date:"2025-01-14"

description:"Meeting Minutes from Python Docs Editorial Board: January 14, 2025"

summary:"Meeting Minutes from Python Docs Editorial Board: January 14, 2025"

tags:["minutes"]

categories:["minutes"]

series:["Meeting Minutes"]

ShowToc:false

TocOpen:false

members:["Guido van Rossum", "Joanna Jablonski", "Ned Batchelder"]

* Revisiting the “how to mark up types” discussion:[https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196/30](https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196/30)

* Erlend said “int or float” (our slight preference) would cause a syntax error for attributes in Sphinx.

* Ned’s quick experiment didn’t cause a syntax error

* Ned has pinged Erlend in Discord for a clarifying conversation.

* If it is a tooling issue, we will rule in favor of “int | float”

* Otherwise, we can rule for “int or float”

* Savannah mentioned an audit

* Joanna will respond on Discourse, inviting Savannah to participate in a docs audit of the argparse pages.

* Starting point:

* Two potential user journeys:

* Making something more basic. Have flags, take in files

* Making something with subcommands, like git. How do you structure that?

* Make them part 1 and part 2 of a how-to?

* Main docs link to how-to(s) with user journeys + reference docs

* We’ve long aspired to doing docs audits, this could be a good baby step

* It is small enough to be approachable

* It can be a way to educate people about what docs audits are and how to do them

* It can be a way for us to reach agreement on how we will do docs audits

* User personas

* How much of this is needed before starting an audit?

author:["Mariatta"]

title:"Meeting Minutes: Feb 11, 2025"

date:"2025-02-11"

description:"Meeting Minutes from Python Docs Editorial Board: February 11, 2025"

summary:"Meeting Minutes from Python Docs Editorial Board: February 11, 2025"

tags:["minutes"]

categories:["minutes"]

series:["Meeting Minutes"]

ShowToc:false

TocOpen:false

members:["Guido van Rossum", "Joanna Jablonski", "Mariatta", "Ned Batchelder"]

guests:["Adam Turner"]

* Doc audit

*[https://github.com/sphinx-doc/sphinx/pull/13242](https://github.com/sphinx-doc/sphinx/pull/13242) -- technicalities about 'or' vs. '|' in Sphinx ':type:' constructs. There appears to be growing support for sticking with '|'

* Star/Slash in function signatures

* Docs audit for argparse: see the “Docs Audit: argparse” doc in resources

* Looks like a good start

* Joanna and Savannah will be collaborating on this in the doc at first

* With some updates in the EB Discord

* They don’t currently need anything from the Board at the moment

* They will pull us in if needed

* Pipes vs “or” in Sphinx type descriptions?

* Adam Turner joins to help

* Adam’s view: we should adopt type annotation syntax

* When that doesn’t work (no type, or “file-like”, etc) we should leave the annotation blank, but still write out the English

* There are three places type information can appear:

* The function signature, which should look like Python code

* If an argument is “file like”, it should be omitted here.

* The argument bullet list

* This is the awkward place: types are parsed here with AST.

* Sphinx possibilities:

* Allow quoted strings, omit the quotes when rendering, and cross-link if the term is in the glossary.

* Try to parse with AST, if it fails, parse with tokenize

* English prose in paragraph form

* If an argument is “file like”, it should be fully described here.

* Plan:

* For non-formal types, use glossary cross-references

* Use pipes instead of prose where possible

* Implementation

* Allow quoted strings as the type annotation

* Unify parsing of field-list style and annotation-style

* Start with custom code for CPython to not have to wait for Sphinx release

* But goal is to upstream it to Sphinx

* Update the discuss.python.org thread with the decision.

* Star/Slash in function signatures

* We want signatures to be precise: if arguments are positional, use a slash, even if there is only one argument.

* We will experiment with Sphinx tooling to provide a link on the slash and star.

* We looked at underline for slash, it was distracting and drew attention to the slash, when most people argue that the slash is already too distracting

* Hover text is a good fallback if a link isn’t an option.

baseURL:"https://python.github.io/editorial-board/"

title:Python Docs Editorial Board

copyright:"© [Python Docs Editorial Board and Contributors](https://github.com/python/editorial-board/graphs/contributors)"

paginate:5

pagination:

pagerSize:5

enableInlineShortcodes:true

enableRobotsTXT:true

{{ end }}

{{ range $guest := .Param "guests" }}

{{ $guest}}

{{ end }}

command ="hugo --gc --minify"

[build.environment]

HUGO_VERSION ="0.119.0"

HUGO_VERSION ="0.128.0"

[context.production.environment]

HUGO_ENV ="production"