Why remove this paragraph? It seems useful for readers to have a summary at the beginning of what the article's going to cover.

A user's eyes will skip over this. They will just bounce off the new reader, for whom they make little connection. They will not add value for the reader who is returning to the page. The links don't take the reader to the topics in the page, but take them away from it, so they don't serve as useful signposts to what's in the page.

If anyone wants to see what's in the page, they can see that immediately from the page's table of contents, where they will find the topics in the context and order of other topics, and can see their place in the hierarchy of concepts.

In general, summaries of what something is going to discuss (and summaries of what has been discussed) add nothing of value to writing. (A summary of conclusions is a quite different matter.)

The links don't take the reader to the topics in the page, but take them away from it, so they don't serve as useful signposts to what's in the page.

I think it's useful to mention functools and itertools early-on as concrete examples of standard-library modules that allow you to use the functional programming style in Python, especially since the opening section is so abstract. I wouldn't mind it if you changed the links so that they pointed to the passages later on in this document where it explores the itertools and functools modules.

This document mostly uses strong-emphasis to indicate a term being defined. To make it consistent:

I think we could drop the versions here and just describe the state of the language in Python 3.x. Maybe drop the first paragraph with "there was no elegant way..." entirely, and the new first paragraph would be something like:

It's also possible to pass values into a generator. The previous examples have used `yield x` alone on a line, as if :keyword:`yield` is a statement, but in fact it's an expression that returns a value that can be assigned to ...

The current wording is more concise. It's also more precise -- with your wording, I'm left wondering who exactly is recommending this? Lots of things in this article are just one person's opinion, and never claim to be anything else, but with your rewording here, it makes it sound like it's the official pronouncement from on high about the proper programming style for Python. Removing the usage of the first person throughout the article really muddies the water here about the purpose of this article, in my opinion.

If they are just one person's opinion, they don't belong in the documentation. The documentation's contract with the user is exactly that: that it is the authoritative pronouncement from on-high about programming in Python. We would never allow the code to be so permissive and lax, to represent merely the way someone feels it's good to do it, and we should hold documentation to the same standards.

If they are just one person's opinion, they don't belong in the documentation.

Says who? Again, that's not how the CPython project has traditionally thought of HOWTO documents, and it's not what the Doc/howto/ directory in CPython has historically been used for. If you want to substantially rewrite a large portion of the articles in Doc/howto/ based on a new, much stricter idea of what it means for a document to be a HOWTO guide, then I honestly think you should try to achieve a broader consensus among the community before going ahead with something like this. I haven't seen any discussions on Discourse about this, for example.

Personally, I think it's great that we have a space in the CPython documentation for more subjective, personal reflections on programming practices. I'd much prefer we say "it's not a how-to" and move it to some other directory than try to turn the document into something it's not.

If they are just one person's opinion, they don't belong in the documentation.

Says who? Again, that's not how the CPython project has traditionally thought of HOWTO documents, and it's not what the Doc/howto/ directory in CPython has historically been used for. If you want to substantially rewrite a large portion of the articles in Doc/howto/ based on a new, much stricter idea of what it means for a document to be a HOWTO guide, then I honestly think you should try to achieve a broader consensus among the community before going ahead with something like this. I haven't seen any discussions on Discourse about this, for example.

I understood - I believe - that there is consensus on adopting Diátaxis for Python's documentation. There have been discussions, I ran a couple of workshops with the documentation team, and so on.

It's a big project, and it's going to take a long time. My goal is to help set new standards of quality in Python's documentation. It is going to change a lot, and set new expectations. There isn't any other way around this.

Personally, I think it's great that we have a space in the CPython documentation for more subjective, personal reflections on programming practices. I'd much prefer we say "it's not a how-to" and move it to some other directory than try to turn the document into something it's not.

Yes, that is precisely what I described as the goal in the original commit for this pull request. These are steps along the way. But even explanation-type documentation, which is what this particular document is, needs to have authority. Otherwise it is simply not documentation.

I understood - I believe - that there is consensus on adopting Diátaxis for Python's documentation.

I've liked a lot of what I've seen from the Diataxis work on the CPython docs -- I think it's resulted in some very worthwhile improvements to the docs, and I'm excited to see it continue! We need to consider each change individually, however. There may be broad consensus about using Diataxis as a framework for the CPython docs overall, but I don't really feel like I've seen any kind of consensus-building about what to do with these older HOWTO documents specifically. Endorsement of a general principle/framework is a pretty different thing to endorsing a specific application of that framework that arguably involves redefining the purpose of an entire directory.

I understand that the pace of the change here might be frustrating for you, and I'm sorry for that, but careful review of each change really is necessary, in my opinion.

I ran a couple of workshops with the documentation team

(Super minor nitpick, but there is no "documentation team". There's a docs community -- a group of people who are interested and enthusiastic about improving the CPython docs. But docs contributions come from a wide variety of people, many of whom aren't part of that community, and there are lots of core developers interested in documentation who aren't part of that community. I think it would be a mistake to assume that the people in that community are necessarily representative of the Python community as a whole 🙂)

Yes, that is precisely what I described as the goal in the original commit for this pull request.

I don't understand -- if the goal is to move this document out of the Doc/howto/ directory, then why do you keep on making arguments based on what a HOWTO is "supposed to be"? If the hope is to reclassify this document altogether, then surely we should do that first, so that we have a clear idea of what the document is meant to be while we're editing it?

I prefer the current wording, which is more concise, and more upfront about the fact that this is one person's opinion.

I doubt I had a personal opinion about catching vs. try...finally, & vaguely think I got the suggestion from somewhere. Could it have been from python-dev discussion when the feature was being added? Or maybe it was just general concern about the complexity of dealing with the GeneratorExit; do you need to re-raise it once your cleanup is done? Maybe this should say "it's simpler to use try...finally" instead of 'recommended'? (And do 3.x async features change any of this?)

This seems to me to be an unnecessary edit

I don't find this necessary

The use of a rhetorical question aimed at the reader has the effect of shaking up the pace of the prose by suddenly throwing in a different kind of sentence construction. I think it's an enjoyable effect, and don't think it needs to be removed

Yeah, most of the changes above to remove 'I suggest' or 'I think' are fine with me, but here the sentence is trying to ask a somewhat punchy question.

I don't understand why this section needs to be deleted. It seems to me to be a useful way of thinking about the problem.

It's true that it's written in a slightly more informal style, and a slightly more humorous style, than a lot of the rest of Python's documentation. But Python's Doc/howto/ directory has historically been home to articles that can be written in a freer, more conversational tone than the rest of Python's documentation.

I disagree with retrofitting a new, stricter definition of what it means for a document to be a HOWTO guide onto Python's Doc/howto/ directory, which has historically had a different concept of what how-to guides are and should be.

A key problem with this page of documentation is that it is not a how-to guide. Whatever else needs to be done with it, it's in the wrong place. If a it does something other than guide the user through a task or problem, it's literally not a how-to guide. Names do matter.

A key problem with this page of documentation is that it is not a how-to guide.

It is a guide that explains how to apply the functional programming paradigm to Python code

Some of these HOWTOs, like this one and the Unicode one, were intros/justifications at the time for newly introduced language features, but now could use editing to just describe the current feature set, with less emphasis on their newness.

I was also hoping that this would encourage others to write HOWTOs on particular topics such as secure Python programming, but that didn't work and sites like Stack Overflow largely took over that function. They could be called something like 'Learning paths' or 'topic guides', but no better term ever became clear.

BTW, here's a more detailed reference for Fredrik Lundh's comment, dated April 1 2001, if you wanted to link it.
https://groups.google.com/g/comp.lang.python/c/qdGhqsmmieo/m/_piGPkADYTgJ

Should it describe Fredrik somehow, as "long-time Python contributor"? Should it specify "the late"?

Is it necessary to keep this "Revision History and Acknowledgements" section?

I think the history can be removed, Acknowledgements could be moved to the end (after References) or removed. The references section should also probably have the 'General' subhead removed (I can't add in-line comments there).

Agreed; we can drop it.

We could also drop the version number at the top of the file.