[issue17894] Edits to descriptor howto

[Ned Batchelder]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Raymond Hettinger]

Changes by Raymond Hettinger :


--
assignee: docs@python -> rhettinger
nosy: +rhettinger
priority: normal -> low

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Ezio Melotti]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Ned Batchelder]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Raymond Hettinger]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Ned Batchelder]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Antoine Pitrou]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Tshepang Lekhonkhobe]

Changes by Tshepang Lekhonkhobe :


--
nosy: +tshepang

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Ned Batchelder]

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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Raymond Hettinger]

Raymond Hettinger added the comment:

I will work on it thank you.

--
versions: +Python 3.7 -Python 3.4

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Ammar Askar]

Ammar Askar  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Raymond Hettinger]

Raymond Hettinger  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Ned Batchelder]

Ned Batchelder  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Ned Batchelder]

Change by Ned Batchelder :


--
resolution: rejected -> 
status: closed -> open

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Raymond Hettinger]

Raymond Hettinger  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17894] Edits to descriptor howto

[Julian Berman]

Julian Berman  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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com