# Editorial Board decisions **URL:** \ **Category:** Documentation\ **Created:** [July 18, 2024, 4:02pm UTC](https://discuss.python.org/t/editorial-board-decisions/58580 "2024-07-18T16:02:59Z")\ **Posts on this page:** 10\ **Page:** 1
**Author:** ![nedbat](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/nedbat/32/8744_2.png) [@nedbat](https://discuss.python.org/u/nedbat)\ **Post date:** [July 18, 2024, 4:02pm UTC](https://discuss.python.org/t/editorial-board-decisions/58580/1 "2024-07-18T16:02:59Z")
The [Python Documentation Editorial Board](https://peps.python.org/pep-0732/) is continuing to pilot our processes for working together. Our decisions will largely be recorded as changes to the Documentation section of the devguide. We recently decided that function signatures in reference material should include the slash and star punctuation that delimit positional-only and keyword-only parameters: [Function signatures should use slash/star as needed by nedbat · Pull Request #1344 · python/devguide · GitHub](https://github.com/python/devguide/pull/1344). We also added a changelog to the editorial-board repo as a way to document decisions on a timeline: [Start a changelog by nedbat · Pull Request #8 · python/editorial-board · GitHub](https://github.com/python/editorial-board/pull/8). For some of our decisions, we’ll want to have broader discussion. We’ll open topics on [discuss.python.org](http://discuss.python.org) where we feel more input is valuable. ---
**Author:** ![skirpichev](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/skirpichev/32/10996_2.png) [@skirpichev](https://discuss.python.org/u/skirpichev)\ **Post date:** [July 19, 2024, 2:18am UTC](https://discuss.python.org/t/editorial-board-decisions/58580/2 "2024-07-19T02:18:35Z")
In this case I would rather support your decision (on the ground “reference material should prioritize precision and completeness”), but I’m little surprised why this case wasn’t discussed outside of PDEB. Last time I was trying to push a [patch](https://github.com/python/cpython/pull/101120) in this direction - it was rejected with a message “There was a decision not to add these to the docs because lay readers mostly find them confusing, because it makes the docs harder to read”. While I was asked several times something along “why help() and sphinx docs show different function signatures?”, I trust @rhettinger teaching experience that such verbose syntax might be confusing. ---
**Author:** ![nedbat](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/nedbat/32/8744_2.png) [@nedbat](https://discuss.python.org/u/nedbat)\ **Post date:** [July 19, 2024, 11:41am UTC](https://discuss.python.org/t/editorial-board-decisions/58580/3 "2024-07-19T11:41:44Z")
In this case, we felt the decision was clear: reference material should be precise. Without the punctuation, important details about the function were missing, or had to be expressed in English. We understand the punctuation is terse and might be unfamiliar. We’d like to explore ways to help new learners understand them in context. The Editorial Board is still fairly new. We’ll adjust processes based on feedback, of course. ---
**Author:** ![encukou](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/encukou/32/2461_2.png) [@encukou](https://discuss.python.org/u/encukou)\ **Post date:** [July 19, 2024, 3:27pm UTC](https://discuss.python.org/t/editorial-board-decisions/58580/4 "2024-07-19T15:27:36Z")
In this case, I’d appreciate if the PR explicitly said that the EB did read and consider previous discussions, in particular [#81315](https://github.com/python/cpython/issues/81315), [#98340](https://github.com/python/cpython/issues/98340) and [SC#12](https://github.com/python/steering-council/issues/12), and still decided the way they did, extending/overriding the [previous decision](https://github.com/python/steering-council/issues/12#issuecomment-498874939). ---
**Author:** ![effigies](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/effigies/32/35835_2.png) [@effigies](https://discuss.python.org/u/effigies)\ **Post date:** [July 19, 2024, 5:53pm UTC](https://discuss.python.org/t/editorial-board-decisions/58580/5 "2024-07-19T17:53:42Z")
> [@nedbat](#): > > We understand the punctuation is terse and might be unfamiliar. We’d like to explore ways to help new learners understand them in context. It could be helpful to auto-tag with `` tags: ```python func1(a, b, /) > func2(*, kwarg1, kwarg2) ``` Rendered: > func1(a, b, /) > func2(\*, kwarg1, kwarg2) `*args` and `**kwargs` could also be tagged, although those are more likely to be addressed in the body of the docstring. I have no idea how helpful/annoying large numbers of `` tags are for screenreader users, but I find the dotted underline is the right level of ignorable-at-will for things like this that are helpful to have at hand until the shorthand becomes familiar. ---
**Author:** ![nedbat](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/nedbat/32/8744_2.png) [@nedbat](https://discuss.python.org/u/nedbat)\ **Post date:** [July 19, 2024, 5:59pm UTC](https://discuss.python.org/t/editorial-board-decisions/58580/6 "2024-07-19T17:59:58Z")
> [@encukou](#): > > In this case, I’d appreciate if the PR explicitly said that the EB did read and consider previous discussions, in particular [#81315](https://github.com/python/cpython/issues/81315), [#98340](https://github.com/python/cpython/issues/98340) and [SC#12](https://github.com/python/steering-council/issues/12), and still decided the way they did, extending/overriding the [previous decision](https://github.com/python/steering-council/issues/12#issuecomment-498874939). You are right, we could have been more explicit about the previous discussions considered. Thanks. ---
**Author:** ![hugovk](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/hugovk/32/14505_2.png) [@hugovk](https://discuss.python.org/u/hugovk)\ **Post date:** [July 19, 2024, 7:01pm UTC](https://discuss.python.org/t/editorial-board-decisions/58580/7 "2024-07-19T19:01:20Z")
> [@effigies](#): > > I have no idea how helpful/annoying large numbers of `` tags are for screenreader users [This device test](https://adrianroselli.com/2024/01/using-abbr-element-with-title-attribute.html#Testing) from January says screen readers mostly do not announce ``s, except for Android/Chrome/Talkback that only announces the `title`, and then a couple that might when using virtual cursor. The `title` is also not exposed in Braille displays, and can’t be accessed by keyboard or touchscreen (for example, mobile phone) users. The [verdict](https://adrianroselli.com/2024/01/using-abbr-element-with-title-attribute.html#Verdict) starts: > Don’t use `` with or without `title`. Exposure continues to be inconsistent across browsers and assistive technologies. Some set of users will always miss some piece of information. ---
**Author:** ![tjreedy](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/tjreedy/32/137_2.png) [@tjreedy](https://discuss.python.org/u/tjreedy)\ **Post date:** [July 19, 2024, 9:07pm UTC](https://discuss.python.org/t/editorial-board-decisions/58580/8 "2024-07-19T21:07:35Z")
I never much liked the previous decision to sometimes leave signatures intentionally incomplete, thus allowing continued questions when users violate the hidden restriction, and discouraging users from using call options when available (because of uncertainty). +1 from me. When `/` first appeared in inspect.signature returns for C functions, I added a note in IDLE tooltips to explain. When they because legal in Python code, I removed them since people needed to learn the option anyway. The referenced ‘previous decision’ said it “can then be revisited for Python 3.9.” We are well past that. ---
**Author:** ![nedbat](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/nedbat/32/8744_2.png) [@nedbat](https://discuss.python.org/u/nedbat)\ **Post date:** [July 20, 2024, 1:49pm UTC](https://discuss.python.org/t/editorial-board-decisions/58580/9 "2024-07-20T13:49:15Z")
I’ve started a new post for specific ideas about how to help people understand the syntax: [Helping people understand function signature syntax](https://discuss.python.org/t/helping-people-understand-function-signature-syntax/58750) ---
**Author:** ![skirpichev](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/skirpichev/32/10996_2.png) [@skirpichev](https://discuss.python.org/u/skirpichev)\ **Post date:** [July 24, 2024, 7:36am UTC](https://discuss.python.org/t/editorial-board-decisions/58580/10 "2024-07-24T07:36:30Z")
Historically, there are several issues, targeted to fix this (e.g. [Use PEP570 syntax in the documentation · Issue #81315 · python/cpython · GitHub](https://github.com/python/cpython/issues/81315), [Missing "/" in function signatures of the rst docs of stdlib (e.g. the math module) · Issue #101118 · python/cpython · GitHub](https://github.com/python/cpython/issues/101118)), all closed. Maybe you should reopen some or create a new one?