I find the explanations in the Descriptor howto to be difficult to understand. I took a stab at changing the first few sections to introduce the concepts in an easier-to-grasp style.

bpo-12077 also covers a little bit of this.

Attached a patch that rephrases part of the suggestions made by Ned.

I worked with Ezio to make a new patch with the full edits.

I have other ideas for edits to the rest of the document, but we can discuss those if you like these...

Please don't go crazy with this. I will look at the suggestions and make some edits to improve its readability but am not going to change it into a breezy conversational style. Instead, I'll likely put together a separate descriptor tutorial that presents an easier on-ramp (in contrast to an authoritative document closely tied to the actually implementation details).

Raymond, I'm glad you're on top of this. I would have thought the howto should be the easy on-ramp, and deeper authoritative details should go in the reference section.

in contrast to an authoritative document closely tied to the actually
implementation details

I fail to understand why a HOWTO should be an authoritative document closely tied to implementation details. If you don't want this document to be beginner-friendly, please move it into the language reference, not the HOWTO directory.

I'm still interested in moving this forward. I can make a GitHub pull request if that would help.

I will work on it thank you.

This seems very very slightly overly conversational (specifically the "That's all there is to it" sentence), but overall like a pretty decent improvement here.

Personally I'd axe that sentence but then seems like this should be merged as-is and any further improvements could always pile on after given how long this has sat.

Any updates on this? Some of the re-organization and simplifications here look pretty good overall and make the guide way more approachable.

Seeing as how this has been sitting a while and Github has an option allow maintainers to make edits to PRs. Raymond, would you be fine with Ned making a PR out of these changes to solicit your feedback and incorporate it the way you want?

I've been working on some updates to the descriptor how-to and will likely post next month or so (there have been other priorities for 3.8 and I had had some limitations regarding posting my training material). I'm going in a different direction than the patches proposed here and am going to mark this tracker issue as closed.

FWIW, this entry is unique in that it is a work of individual authorship, originally posted on my own website. When the analysis became a popular, I was asked to post it on python.org. I will continue to maintain and improve it but am not open to a substantial stylistic rewrite changing it into someone else's style (people can use their own blog posts for that purpose).

I think it's a bad precedent to have pages in the official docs that belong to a single author. If you want to maintain that kind of control, it should go on your blog. Part of the agreement for having material added to the official docs should be the understanding that they are fair game for community contributions.

I am actively working on updates. However, the work on Python 3.8's whatsnew and doc fixes are a more immediate priority. Cumulatively, I've put an a lot of effort in to this and have made a continuous stream of improvements over the years including this year. In a way, maintaining this entry is not much different from being a module maintainer who has the principal responsibility and authority over the updates. This is something that I frequently teach and have battle tested course material that I'm looking forward to including in the entry.

Please give me space and don't shove. IMO some of the past posts on this subject are border-line abusive, leaving me feeling hounded and degraded (especially with respect to my writing style). Please be kind and let me continue to improve my contribution at my own pace.

Please don't re-open this issue. I have marked the patch as rejected because it is at odds with the improvements that I already have in progress and because some of it is essentially just a stylistic difference.