classification
Title: Edits to descriptor howto
Type: Stage: resolved
Components: Documentation Versions: Python 3.7
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: Julian, ammar2, docs@python, ezio.melotti, nedbat, pitrou, rhettinger, tshepang
Priority: low Keywords: patch

Created on 2013-05-03 02:11 by nedbat, last changed 2019-10-11 01:30 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
descriptor_howto.patch nedbat, 2013-05-03 02:11 review
issue17894.diff ezio.melotti, 2013-05-04 18:05 review
descriptor_howto_2.patch nedbat, 2013-05-04 23:33 The new patch, incorporating the other two. review
Messages (13)
msg188289 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2013-05-03 02:11
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.
msg188384 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-05-04 18:05
Attached a patch that rephrases part of the suggestions made by Ned.
msg188418 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2013-05-04 23:33
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...
msg188421 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013-05-05 02:25
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).
msg188423 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2013-05-05 02:37
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.
msg188429 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2013-05-05 06:27
> 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.
msg288666 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2017-02-27 20:21
I'm still interested in moving this forward. I can make a GitHub pull request if that would help.
msg288690 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2017-02-28 04:20
I will work on it thank you.
msg320796 - (view) Author: Julian Berman (Julian) * Date: 2018-06-30 17:31
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.
msg354304 - (view) Author: Ammar Askar (ammar2) * (Python triager) Date: 2019-10-10 01:10
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?
msg354311 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-10-10 03:24
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).
msg354366 - (view) Author: Ned Batchelder (nedbat) * (Python triager) Date: 2019-10-10 11:41
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.
msg354416 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-10-11 01:30
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.
History
Date User Action Args
2019-10-11 01:30:05rhettingersetstatus: open -> closed
resolution: rejected
messages: + msg354416
2019-10-10 18:15:32nedbatsetstatus: closed -> open
resolution: rejected -> (no value)
2019-10-10 11:41:49nedbatsetmessages: + msg354366
2019-10-10 03:24:33rhettingersetstatus: open -> closed
resolution: rejected
messages: + msg354311

stage: resolved
2019-10-10 01:10:51ammar2setnosy: + ammar2
messages: + msg354304
2018-06-30 17:31:44Juliansetnosy: + Julian
messages: + msg320796
2017-02-28 04:20:45rhettingersetmessages: + msg288690
versions: + Python 3.7, - Python 3.4
2017-02-27 20:21:01nedbatsetmessages: + msg288666
2013-06-19 08:44:58tshepangsetnosy: + tshepang
2013-05-05 06:27:42pitrousetnosy: + pitrou
messages: + msg188429
2013-05-05 02:37:50nedbatsetmessages: + msg188423
2013-05-05 02:25:29rhettingersetmessages: + msg188421
2013-05-04 23:33:23nedbatsetfiles: + descriptor_howto_2.patch

messages: + msg188418
2013-05-04 18:05:17ezio.melottisetfiles: + issue17894.diff
nosy: + ezio.melotti
messages: + msg188384

2013-05-03 09:47:26rhettingersetpriority: normal -> low
assignee: docs@python -> rhettinger

nosy: + rhettinger
2013-05-03 02:11:51nedbatcreate