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

Created on 2013-05-03 02:11 by nedbat, last changed 2018-06-30 17:31 by Julian.

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 (9)
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.
History
Date User Action Args
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