Re: PyWart: Poor Documentation Examples
Ethan Furman wrote: On 01/10/2015 06:32 PM, Steven D'Aprano wrote: If you treat your readers as idiots, only idiots will read your writing. Or the morbidly curious, which I presume covers your case (along with a handful of others ;) . Reading Rick is like taking bad drugs. Every time I've had it in the past, it was a bad trip. I know that this time it's going to be a bad trip. And yet I just can't help myself. If that isn't a form of stupidity, I don't know what is. -- Steven -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
On Sunday, January 11, 2015 at 10:56:11 AM UTC+5:30, Devin Jeanpierre wrote: On Sat, Jan 10, 2015 at 6:32 PM, Steven D'Aprano wrote: At the point you are demonstrating reduce(), if the reader doesn't understand or can't guess the meaning of n = 4, n+1 or range(), they won't understand anything you say. Teachers need to understand that education is a process of building upon that which has come before. If the teacher talks down to the student by assuming that the student knows nothing, and tries to go back to first principles for every little thing, they will never get anywhere. Agree wholeheartedly. That said, I do think reduce(operator.mul, [1, 2, 3, 4]) actually _is_ a better example, since it cuts right to the point. In keeping with Rick's super-polite suggestion to remove irreleventia like range and variables(!), if we are about to improve that doc, I would remove the 1,2,3,4 pattern as well and replace with something more random. The mathematically minded student may think that this has something to do with arithmetic progressions, that it does clever algebraic simplifications like 횺 i = n(n+1)/2 A favorite example of mine is automata-acceptance: If δ : Q × Σ → Q is a transition function F is the set of final states q₀ is the start state and s is a string then reduce(δ,q₀,s) ∈ F expresses automaton accepts string s Should that go into the doc?? I'll leave that to somebody else whose name starts with 'R' :-) -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
On Sun, 11 Jan 2015 06:20:34 -0800, Rustom Mody wrote: A favorite example of mine is automata-acceptance: If δ : Q × Σ → Q is a transition function F is the set of final states q₀ is the start state and s is a string then reduce(δ,q₀,s) ∈ F expresses automaton accepts string s Should that go into the doc?? Absolutely. :-) If the docs had explained that reduce is actually a finite state machine framework, then I wouldn't have written my such framework. I'll leave that to somebody else whose name starts with 'R' :-) Uh, oh. Sorry. -- Dan Sommers, neither of which begins with an 'R' -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
On Mon, Jan 12, 2015 at 3:04 AM, Grant Edwards invalid@invalid.invalid wrote: On 2015-01-10, Chris Angelico ros...@gmail.com wrote: 1) Why are you focusing on the /2/ docs, rather than /3/? 2) Why are you ranting, rather than submitting docs patches? 3) There are still people who read RR posts? Yeah, there are. Steven summarized it thus, although I can't personally speak to the accuracy of the specifics: On Sun, Jan 11, 2015 at 8:31 PM, Steven D'Aprano steve+comp.lang.pyt...@pearwood.info wrote: Reading Rick is like taking bad drugs. Every time I've had it in the past, it was a bad trip. I know that this time it's going to be a bad trip. And yet I just can't help myself. If that isn't a form of stupidity, I don't know what is. ChrisA -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
On 01/11/2015 09:04 AM, Grant Edwards wrote: 3) There are still people who read RR posts? The last post by RR helping someone with a tk problem was very helpful, and rather elucidating, as are most of his post on tk. It was rather refreshing to see several posts like this. I thought perhaps this would signify a new era. But alas, no, he's slipped back into his lazy ways. Too bad really. He seems to be a smart person. He could contribute to Python in positive ways if he chose (like patching the documentation, or contributing code). Unfortunately when he gets like this he can't even get up the energy to open bug reports. Easier to just rant on the list apparently. Now perhaps there are two RRs, in some sort of conflict in the same person. Sad to see this one winning out. -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
On 2015-01-10, Chris Angelico ros...@gmail.com wrote: On Sun, Jan 11, 2015 at 5:05 AM, Rick Johnson rantingrickjohn...@gmail.com wrote: EXAMPLE 1: Reducing Comprehension https://docs.python.org/2/howto/doanddont.html#using-the-batteries 1) Why are you focusing on the /2/ docs, rather than /3/? 2) Why are you ranting, rather than submitting docs patches? 3) There are still people who read RR posts? -- Grant -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
On Mon, Jan 12, 2015 at 4:11 AM, Michael Torrie torr...@gmail.com wrote: The last post by RR helping someone with a tk problem was very helpful, and rather elucidating, as are most of his post on tk. ... Now perhaps there are two RRs, in some sort of conflict in the same person. Sad to see this one winning out. Doubtful. Even when he's answering tkinter questions (and is imparting useful information), he still has the same abrasive style. It reflects badly on Python that the help is provided in such a way, but unless there's someone else with as much expertise as Rick has, that's not going to change. (Either that, or we just all start recommending PyQT or GTK or something.) ChrisA -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
On Sunday, January 11, 2015 at 10:49:11 PM UTC+5:30, Chris Angelico wrote: On Mon, Jan 12, 2015 at 4:11 AM, Michael Torrie wrote: The last post by RR helping someone with a tk problem was very helpful, and rather elucidating, as are most of his post on tk. ... Now perhaps there are two RRs, in some sort of conflict in the same person. Sad to see this one winning out. Doubtful. Even when he's answering tkinter questions (and is imparting useful information), he still has the same abrasive style. It reflects badly on Python that the help is provided in such a way, but unless there's someone else with as much expertise as Rick has, that's not going to change. (Either that, or we just all start recommending PyQT or GTK or something.) You can always tell the unwitting new questioner that Rick's content is useful [when it is] whereas his style is ignorable. -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
On 11/01/2015 16:04, Grant Edwards wrote: On 2015-01-10, Chris Angelico ros...@gmail.com wrote: On Sun, Jan 11, 2015 at 5:05 AM, Rick Johnson rantingrickjohn...@gmail.com wrote: EXAMPLE 1: Reducing Comprehension https://docs.python.org/2/howto/doanddont.html#using-the-batteries 1) Why are you focusing on the /2/ docs, rather than /3/? 2) Why are you ranting, rather than submitting docs patches? 3) There are still people who read RR posts? Admittedly this was a bad one but his contributions to tkinter/IDLE are useful. Contrast that to our former Resident Unicode Expert or our Greek Web Design Expert. Then years ago there was Xah Lee telling us how to write docs, it was so funny the way he was torn to shreds. As for Ilias Lazaridu what can I say, except that I beat all when having a day that starts with me getting out of bed on the wrong side, and worse later on when my hair do gets ruined!!! :) -- My fellow Pythonistas, ask not what our language can do for you, ask what you can do for our language. Mark Lawrence -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
On 11/01/2015 7:31 PM, Steven D'Aprano wrote: If that isn't a form of stupidity, I don't know what is. Maybe you're just eternally optimistic that people can change for the better. -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
On Sun, Jan 11, 2015 at 5:05 AM, Rick Johnson rantingrickjohn...@gmail.com wrote: EXAMPLE 1: Reducing Comprehension https://docs.python.org/2/howto/doanddont.html#using-the-batteries 1) Why are you focusing on the /2/ docs, rather than /3/? 2) Why are you ranting, rather than submitting docs patches? Your school bell is muted. ChrisA -- https://mail.python.org/mailman/listinfo/python-list
PyWart: Poor Documentation Examples
EXAMPLE 1: Reducing Comprehension https://docs.python.org/2/howto/doanddont.html#using-the-batteries #QUOTE: Python Docs# # Another highly useful function is reduce() which can be # # used to repeatly apply a binary operation to a sequence, # # reducing it to a single value. For example, compute a# # factorial with a series of multiply operations: # # # # py n = 4# # py import operator # # py reduce(operator.mul, range(1, n+1)) # # 24 # Ignoring the obvious mis-spellings @_@... How exactly does: assigning variables(n = 4), arithmetic(n+1), and the range function going to help me understand the usefulness of the reduce function? A much better example would be: py import operator py reduce(operator.mul, [1,2,3,4]) 24 At *LEAST* with that example the only potential unknown might be operator.mul. However, a wise teacher would recognize that this is a fine teaching example of how using the operator module can prevent duplicating code -- which would lead to a better example like: py def mul(x, y): ... return x*y py reduce(mul, [1,2,3,4]) 24 FINALLY! An example that showcases a proper usage of the the reduce function *WITHOUT* any superfluous distractions. However, remembering that code re-use is a good thing, and that re- inventing the wheel is a lot of work, we should mention that the mul function should be replaced with operator.mul Note: Be sure to check out the operator module for pre-defined arithmetic functions like operator.mul, which would reduce (*wink*) the above code to this: py reduce(operator.mul, [1,2,3,4]) 24 EXAMPLE 2: The Fibonacci Phallus Extender. https://docs.python.org/2/tutorial/controlflow.html#defining-functions # # QUOTE: Python Docs # # # We can create a function that writes the Fibonacci# # series to an arbitrary boundary: # # # # py def fib(n):# write Fibonacci series up to n # # ... Print a Fibonacci series up to n. # # ... a, b = 0, 1 # # ... while a n: # # ... print a, # # ... a, b = b, a+b # # ... # # py # Now call the function we just defined: # # ... fib(2000) # # 0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 # # No, No, *NO*! This is the most horrible example i have ever encountered. Why would you introduction functions with an example of calculating Fibonacci series? How are doc-strings and multiple assignment and loops and conditions the print function and comments going to help me understand defining a python function? Listen, if your primary goal is to teach, then *BEFORE* you provide *ANY* examples of defining functions, you should *FIRST* explain what a function *IS* and *WHY* you would want to use one. Next we going to learn about defining functions, but before we do, we need to understand *WHAT* a function *IS* and *WHY* we should use them ... [LAZY DOC WRITERS CAN INSERT EXTERNAL LINK HERE!] Now that we've explained the *what* and *why* of functions, we need to provide an example of the most *BASIC* of python function definitions: py def add(x, y): return x + y py add(1,1) 2 *SCHOOL-BELL-RINGS* -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
On 10/01/2015 18:26, Chris Angelico wrote: On Sun, Jan 11, 2015 at 5:05 AM, Rick Johnson rantingrickjohn...@gmail.com wrote: EXAMPLE 1: Reducing Comprehension https://docs.python.org/2/howto/doanddont.html#using-the-batteries 1) Why are you focusing on the /2/ docs, rather than /3/? 2) Why are you ranting, rather than submitting docs patches? Your school bell is muted. ChrisA Ooh, I say old chap, isn't that going a bit too far? Users submitting patches, whatever next? -- My fellow Pythonistas, ask not what our language can do for you, ask what you can do for our language. Mark Lawrence -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
Rick Johnson wrote: EXAMPLE 1: Reducing Comprehension https://docs.python.org/2/howto/doanddont.html#using-the-batteries #QUOTE: Python Docs# # Another highly useful function is reduce() which can be # # used to repeatly apply a binary operation to a sequence, # # reducing it to a single value. For example, compute a# # factorial with a series of multiply operations: # # # # py n = 4# # py import operator # # py reduce(operator.mul, range(1, n+1)) # # 24 # How exactly does: assigning variables(n = 4), arithmetic(n+1), and the range function going to help me understand the usefulness of the reduce function? Obviously they don't, duh. They're mere incidentals. A much better example would be: py import operator py reduce(operator.mul, [1,2,3,4]) 24 But Rick, my o-so-wise teacher, what's this stuff with the square brackets and commas? And the round brackets (or parentheses as the Americans call them)? At the point you are demonstrating reduce(), if the reader doesn't understand or can't guess the meaning of n = 4, n+1 or range(), they won't understand anything you say. Teachers need to understand that education is a process of building upon that which has come before. If the teacher talks down to the student by assuming that the student knows nothing, and tries to go back to first principles for every little thing, they will never get anywhere. In this case, it is perfectly acceptable to assume that by the time the beginner gets to a document about Dos and Don'ts they are comfortable with such basic concepts as assigning values to variables n=4, addition n+1, importing, and can interpret from the context that operator.mul multiplies without needing to be explicitly told. If you treat your readers as idiots, only idiots will read your writing. At *LEAST* with that example the only potential unknown might be operator.mul. However, a wise teacher would recognize that this is a fine teaching example of how using the operator module can prevent duplicating code -- And the version on the docs demonstrates this by example, instead of patronising the reader and treating them as an eight year old who needs to have the most trivial things explained to them. which would lead to a better example like: py def mul(x, y): ... return x*y py reduce(mul, [1,2,3,4]) 24 But Rick, my o-so-wise teacher! What is the meaning of 'def', 'return' and the asterisk between the x and y? What's with the three dots and the spaces? FINALLY! An example that showcases a proper usage of the the reduce function *WITHOUT* any superfluous distractions. Apart from having to define your own function. Given that this is a document intended to show-case best practice (as in Do this, Don't do that) it is completely inappropriate to encourage the reader to re-invent the wheel by creating their own (slow) mul function instead of importing the (fast) pre-built one in the operator module. However, remembering that code re-use is a good thing, and that re- inventing the wheel is a lot of work, we should mention that the mul function should be replaced with operator.mul No, we should not mention it as an aside. We should demonstrate best practice from the start. Unless you are writing for beginners who haven't been introduced to importing yet (in which case, why are you teaching them reduce() so early?) there is no benefit at all in showing people how *not* to do it, then jokingly give them a little nudge-nudge-wink-wink by the way, this is better aside. Note: Be sure to check out the operator module for pre-defined arithmetic functions like operator.mul, which would reduce (*wink*) the above code to this: py reduce(operator.mul, [1,2,3,4]) 24 EXAMPLE 2: The Fibonacci Phallus Extender. And that's where I stopped reading. I'm sure it will be overflowing with insights of your usual quality, but I hurt myself laughing so hard at your wit (ha ha, phallus, that means the D) that I simply couldn't continue. -- Steven -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
On Sat, Jan 10, 2015 at 6:32 PM, Steven D'Aprano steve+comp.lang.pyt...@pearwood.info wrote: At the point you are demonstrating reduce(), if the reader doesn't understand or can't guess the meaning of n = 4, n+1 or range(), they won't understand anything you say. Teachers need to understand that education is a process of building upon that which has come before. If the teacher talks down to the student by assuming that the student knows nothing, and tries to go back to first principles for every little thing, they will never get anywhere. Agree wholeheartedly. That said, I do think reduce(operator.mul, [1, 2, 3, 4]) actually _is_ a better example, since it cuts right to the point. -- Devin -- https://mail.python.org/mailman/listinfo/python-list
Re: PyWart: Poor Documentation Examples
On Sunday, January 11, 2015 at 8:02:50 AM UTC+5:30, Steven D'Aprano wrote: Rick Johnson wrote: EXAMPLE 1: Reducing Comprehension https://docs.python.org/2/howto/doanddont.html#using-the-batteries #QUOTE: Python Docs# # Another highly useful function is reduce() which can be # # used to repeatly apply a binary operation to a sequence, # # reducing it to a single value. For example, compute a# # factorial with a series of multiply operations: # # # # py n = 4# # py import operator # # py reduce(operator.mul, range(1, n+1)) # # 24 # How exactly does: assigning variables(n = 4), arithmetic(n+1), and the range function going to help me understand the usefulness of the reduce function? Obviously they don't, duh. They're mere incidentals. A much better example would be: py import operator py reduce(operator.mul, [1,2,3,4]) 24 But Rick, my o-so-wise teacher, what's this stuff with the square brackets and commas? And the round brackets (or parentheses as the Americans call them)? At the point you are demonstrating reduce(), if the reader doesn't understand or can't guess the meaning of n = 4, n+1 or range(), they won't understand anything you say. Teachers need to understand that education is a process of building upon that which has come before. If the teacher talks down to the student by assuming that the student knows nothing, and tries to go back to first principles for every little thing, they will never get anywhere. In this case, it is perfectly acceptable to assume that by the time the beginner gets to a document about Dos and Don'ts they are comfortable with such basic concepts as assigning values to variables n=4, addition n+1, importing, and can interpret from the context that operator.mul multiplies without needing to be explicitly told. If you treat your readers as idiots, only idiots will read your writing. At *LEAST* with that example the only potential unknown might be operator.mul. However, a wise teacher would recognize that this is a fine teaching example of how using the operator module can prevent duplicating code -- And the version on the docs demonstrates this by example, instead of patronising the reader and treating them as an eight year old who needs to have the most trivial things explained to them. which would lead to a better example like: py def mul(x, y): ... return x*y py reduce(mul, [1,2,3,4]) 24 But Rick, my o-so-wise teacher! What is the meaning of 'def', 'return' and the asterisk between the x and y? What's with the three dots and the spaces? FINALLY! An example that showcases a proper usage of the the reduce function *WITHOUT* any superfluous distractions. Apart from having to define your own function. Given that this is a document intended to show-case best practice (as in Do this, Don't do that) it is completely inappropriate to encourage the reader to re-invent the wheel by creating their own (slow) mul function instead of importing the (fast) pre-built one in the operator module. However, remembering that code re-use is a good thing, and that re- inventing the wheel is a lot of work, we should mention that the mul function should be replaced with operator.mul No, we should not mention it as an aside. We should demonstrate best practice from the start. Unless you are writing for beginners who haven't been introduced to importing yet (in which case, why are you teaching them reduce() so early?) there is no benefit at all in showing people how *not* to do it, then jokingly give them a little nudge-nudge-wink-wink by the way, this is better aside. Note: Be sure to check out the operator module for pre-defined arithmetic functions like operator.mul, which would reduce (*wink*) the above code to this: py reduce(operator.mul, [1,2,3,4]) 24 EXAMPLE 2: The Fibonacci Phallus Extender. And that's where I stopped reading. I'm sure it will be overflowing with insights of your usual quality, but I hurt myself laughing so hard at your wit (ha ha, phallus, that means the D) that I simply couldn't continue. -- Steven Rick: Your style beyond irritating to
Re: PyWart: Poor Documentation Examples
On 01/10/2015 06:32 PM, Steven D'Aprano wrote: If you treat your readers as idiots, only idiots will read your writing. Or the morbidly curious, which I presume covers your case (along with a handful of others ;) . -- ~Ethan~ signature.asc Description: OpenPGP digital signature -- https://mail.python.org/mailman/listinfo/python-list
