PEPs should include a section on "teachability"

[warsaw]

copied from python-dev

I had occasional to speak with someone very involved in Rust development. They have a process roughly similar to our PEPs. One of the things he told me, which I found very interesting and have been mulling over for PEPs is, they require a section in their specification discussion how any new feature will be taught, both to new Rust programmers and experienced ones. I love the emphasis on teachability. Sometimes I really miss that when considering some of the PEPs and the features they introduce (look how hard it is to teach asynchronous programming).

Paul Moore suggests this could go in a guideline for writing PEPs. Or maybe it should go in PEP 1?

[Rosuav]

Sounds like something worth including in PEP 12. I'm -0.5 on requiring it in every PEP, but +1 on having a nice template that hints at important sections. In fact, I'd go a bit further and have other useful sections in PEP 12, eg "Backward compatibility" (or "Impact on existing code") and "Sample implementation", with bodies explaining the purposes of those sections. PEP authors can remove those sections if they don't apply, or keep them and flesh them out.

The template would then almost be a checklist, which IMO is a Good Thing™.

[njsmith]

There's this checklist in PEP 1: https://www.python.org/dev/peps/pep-0001/#what-belongs-in-a-successful-pep
(The text there suggests that every PEP should have all of those sections, but in practice people ignore that when it doesn't make sense.)

Right now PEP 12 is mostly a ReST tutorial. It does seem like something more PEP-specific might be a better use of that space.

[Rosuav]

Yeah, I know about that list, but IMO a template is a more effective checklist. A ReST tutorial is a good thing, but a PEP template can be so much more.

[Mariatta]

I agree with @njsmith about adding this as part of PEP 1 under "What belongs in a successful PEP".

For now PEP 12 seems more of a set of instructions or a tutorial, instead of a template, for me anyways. When I think of a template, I think of a cookiecutter-like template :)

[Rosuav]

I agree, Mariatta, a template should be something that you can actually grab and use. PEP 12 has instructions at the top that act like that, but then the rest of the content isn't all template-y. So my view is that we should push for PEP 12 to be more template-y :)

[warsaw]

On Nov 29, 2017, at 13:28, Chris Angelico ***@***.***> wrote: I agree, Mariatta, a template should be something that you can actually grab and use. PEP 12 has instructions at the top that act like that, but then the rest of the content isn't all template-y. So my view is that we should push for PEP 12 to be more template-y :)

+1 - that’s certainly the intent implied by the title of the PEP <wink>

[Mariatta]

Sounds good! 😆 Well let's update PEP 1 already!

[encukou]

PEP 1 is now updated. Please continue PEP 12 discussion over at #655; I've copied some relevant comments there.