PEP 677: Readability and organizational edits (#2193)

* Address Guido's comments from initial PR

* Update functions-as-types based on Pradeep's feedback

* Fix some markup, address comments on endpoint example

* Rearrange Motivation and Rationale

* Move the language comparison subsection to Rational

* Fix more markup errors

* Rework "Motivation" section again

Going with Pradeep's suggested order:
- untyped example
- correct types
- partially-typed code
- our proposal

* Fix more lint errors

* Add a section highlighting a concern about -> readability

* Update the add/wrap/flatmap example

* Wording change suggested by AlexWaygood

* Add missing return annotation

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

* Break up long sentence

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

* Break up long sentence (thanks Jelle)

* Reword awkward sentence (thanks Pradeep)

* Rearrange paragraphs in Motivation

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

Author: 3 people