PEP 1: Update the "How to teach this" section

[Mariatta]

Instead of the "How to teach this", ask for
documentation updates to accompany the new PEP.

• Change is either:
  • To an Accepted or Final PEP, with Steering Council approval
• PR title prefixed with PEP number (e.g. PEP 123: Summary of changes)

cc @python/editorial-board

Closes #4040

---

📚 Documentation preview 📚: https://pep-previews--4041.org.readthedocs.build/

[Mariatta]

Hi, will this require Steering Council approval?

[warsaw]

Hi @Mariatta. I put this question to the SC Discord but my personal feeling is that it's not either-or. I like the addition to outline where documentation changes need to happen, but I still think a "teach this" section can be valuable. What do you think about keeping both?

[willingc]

#4040 (comment)

@warsaw: @Mariatta, Guido, and I had discussed that the "How to teach" section was overly broad and caused a bit of confusion about what it should contain. I think there is value to having a documentation section in the PEP as well as a section that provides an "explanation" to users beyond core devs as mentioned in my comment. I think these two can be combined into one section.

[ncoghlan]

I think "How to Teach This" is still a good name for the recommended section title (since the potential scope for changes is larger than just the CPython documentation), but we should make it clear in PEP 1 that for changes to already documented features, it's OK for this section of a PEP to just say something like:

This is a change to an already documented feature. The documentation at {link to existing docs} will be updated appropriately as part of implementing this PEP.

We could also point to concrete examples from existing accepted PEPs (such as the single paragraph in the "Exception Groups" PEP) to indicate that it's OK to start super simple in this section, and only expand it if concerns are raised with the baseline "this can just be covered in the existing docs" approach during the PEP review process.