[gvanrossum]

Don't merge until @cdce8p (Marc Müller, the PEP author) has approved this.

[Copilot]

🟢 Approval recommended

The documentation-only changes explain the proposed behavior consistently, with no blocking issues identified.

No open issues 🎉

What changed in this PR

Expands PEP 823’s teaching guidance into a mini-tutorial for the proposed None-aware operators.

Changes:

• Adds prerequisites, examples, chaining rules, and caveats.
• Explains when to use—and avoid—the operators.
• Removes an outdated cross-reference to the teaching section.

File	Description
peps/​pep-0823.rst	Expands teaching guidance and adjusts related explanatory text.

_{Review effort: Balanced}

[read-the-docs-community]

Documentation build overview

📚 pep-previews | 🛠️ Build #35276353 | 📁 Comparing 27e5bf0 against latest (d5d2571)

  🔍 Preview build  

10 files changed · ± 9 modified · - 1 deleted

± Modified

• index.html
• numerical/index.html
• pep-0000/index.html
• pep-0774/index.html
• pep-0817/index.html
• pep-0823/index.html
• pep-0836/index.html
• pep-0850/index.html
• topic/packaging/index.html

- Deleted

• pep-0817/appendix-variant-metadata-json-schema/index.html

[cdce8p]

Thanks for putting this together! I agree let's include it, it's a much better use for that section. Left some minor comments.

[cdce8p]

It might also be good to add a short note to the (to be created) Change History section (after the footnotes).

[gvanrossum]

@cdce8p If you have any concerns with my changes in response to your feedback, let's open a new PR to address those concerns.

[cdce8p]

Nothing more to add here. Thanks again @gvanrossum!