PEP 1: Replace/Update the "How to teach this" with "Documentation Updates"

[Mariatta]

I would like to suggest an update to the "How to teach this" section in PEPs to "Documentation Updates".

As part of proposing new features or changes, it would be great if PEP authors also take into consideration of what docs need to be produced/updated.

For example, would the PEP require changes to the how-to doc? Will there be new tutorial section written? What other areas of Python docs need to be updated to accommodate this new change? Are there existing docs that will become outdated and need changing? I think all of these should be taken into consideration when proposing changes so that we can have up to date documentation alongside the changes.

I think the "How to teach this" section meant to address this, but in practise I find the use of this section has been inconsistent, so I recommend making the section be more explicit about documentation artifacts to accompany the feature/change.

I also find some of the "How to teach this" in current PEPs sometimes are sounding can sound hypothetical. I'm seeing phrases like "Teachers could say so and so to students".

Instead of imagining what teachers could say, I think it would be more helpful to come up with concrete plan of what documentation can be produced to assist users in learning and adopting the feature/change.

[hugovk]

I quite like the current heading, as it's broader than just documentation.

For example, I included some non-docs things in PEP 2026.

However, I agree it would be good to encourage more a concrete docs plan.

[AA-Turner]

Likewise, I think encouraging authors to consider the learning process is useful, and has broader implications than only our documentation.

Perhaps we could change the "may" to "should" in the current text?:

This section may include key points and recommended documentation changes that would help users adopt a new feature or migrate their code to use a language change.

A

[Mariatta]

For example, I included some non-docs things in PEP 2026.

The How to teach this for PEP 2026 is as follows:

We will announce this on blogs, in the 3.14 release notes, documentation, and through outreach to the community.

"This change targets the version following 3.14: instead of 3.15 it will be 3.26. This PEP was proposed in June 2024. Development for the 3.15/3.26 release will begin in May 2025, with the first alpha in October 2025 and initial release in October 2026. We can already update documentation during the 3.14 cycle. This gives plenty of notice."

I like this "promotional" plan, and I wish we do more of this on all the PEPs.

I realize I may be bikeshedding on the name, but the above paragraph also doesn't sound like "teaching" but more "documentation", "how to announce, how we will announce it', "community outreach plan". So limiting to "how to teach" also seemed inaccurate to me.

We can make preview builds which only change the version for early testing.

I wish it was phrased as "We will make preview builds", and I think this seemed to be more relevant under the PEP implementation itself. By creating preview builds, it will help other users evaluate the change ahead of time and provide feedback. I don't teach people, but I will look at preview builds for myself. So to me, preview builds are relevant to wider audiences, not just for "teaching".

We could ship a python3.15 command as part of Python 3.26 that immediately errors out and tells the user to use python3.26 instead.

I also wish this is listed as part of PEP implementation detail instead of under "how to teach", e.g. phrased as: "we will ship a ...."

To me, "Documentation" has broader meaning than "Teaching".

Documentation can include the release notes and tutorials. Tutorials can be used in teaching context, it can be used by teachers as inspiration on how to prepare their own content, it can be used by learners to learn. "How to teach" seemed relevant only to a narrower group of people: people who teach/educate. This is not the same of group of people who do outreach, and not the same people doing the learning.

Simply telling people "here's the doc", "here's the error message", is not the same as "teaching". So I still think "Documentation" has a wider scope, and we can still include content about teaching recommendations under the doc section, as a "tutorial plan".

I'm also under the impression that PEPs are for proposals and not the final doc. After a PEP has been implemented, teachers and educators should be looking at Python docs for information, not the PEP. So educators, users, and learners should be reading Python docs to learn about things, and not the PEP. I just don't think pointing to the educators, "hey look at this PEP on suggestions how to teach to your students", is the right way. But maybe this is something we should get feedback from the educators.

[willingc]

Perhaps "How to explain and document"

I'm going to push back gently on the need to understand how to explain the feature to non-core developers. It's not just teachers who need the explanation but maintainers of large projects, such as the scientific ecosystem.

Sometimes PEPs go so deep in the technical weeds that a clear explanation to other developers gets overlooked. Making the explanation explicit and documentation plan highlighted seems reasonable to me.