[issue17894] Edits to descriptor howto

New submission from Ned Batchelder: 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. Issue 12077 also covers a little bit of this. ---------- assignee: docs@python components: Documentation files: descriptor_howto.patch keywords: patch messages: 188289 nosy: docs@python, nedbat priority: normal severity: normal status: open title: Edits to descriptor howto versions: Python 3.4 Added file: http://bugs.python.org/file30111/descriptor_howto.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17894> _______________________________________

Changes by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- assignee: docs@python -> rhettinger nosy: +rhettinger priority: normal -> low _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17894> _______________________________________

Ezio Melotti added the comment: Attached a patch that rephrases part of the suggestions made by Ned. ---------- nosy: +ezio.melotti Added file: http://bugs.python.org/file30125/issue17894.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17894> _______________________________________

Ned Batchelder added the comment: 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... ---------- Added file: http://bugs.python.org/file30127/descriptor_howto_2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17894> _______________________________________

Raymond Hettinger added the comment: 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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17894> _______________________________________

Ned Batchelder added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17894> _______________________________________

Antoine Pitrou added the comment:
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. ---------- nosy: +pitrou _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17894> _______________________________________

Changes by Tshepang Lekhonkhobe <tshepang@gmail.com>: ---------- nosy: +tshepang _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17894> _______________________________________

Ned Batchelder added the comment: I'm still interested in moving this forward. I can make a GitHub pull request if that would help. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17894> _______________________________________

Raymond Hettinger added the comment: I will work on it thank you. ---------- versions: +Python 3.7 -Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17894> _______________________________________

Julian Berman <Julian+Python.org@GrayVines.com> added the comment: 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. ---------- nosy: +Julian _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue17894> _______________________________________

Ammar Askar <ammar@ammaraskar.com> added the comment: 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? ---------- nosy: +ammar2 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue17894> _______________________________________

Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: 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). ---------- resolution: -> rejected stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue17894> _______________________________________

Ned Batchelder <ned@nedbatchelder.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue17894> _______________________________________

Change by Ned Batchelder <ned@nedbatchelder.com>: ---------- resolution: rejected -> status: closed -> open _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue17894> _______________________________________

Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: 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. ---------- resolution: -> rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue17894> _______________________________________
participants (7)
-
Ammar Askar
-
Antoine Pitrou
-
Ezio Melotti
-
Julian Berman
-
Ned Batchelder
-
Raymond Hettinger
-
Tshepang Lekhonkhobe