[Tutor] How is "set(ls).add('a') evaluated? [Was: Re: A program that can check if all elements of the list are mutually disjoint]

[Mats Wichmann]

On 6/7/21 3:40 PM, dn via Tutor wrote:

> For your reading pleasure:
> <<<
> Batchelder observed that "twenty-five years ago, our main audience
> seemed to be refugees from C," but most readers of the Python docs today
> are not career software developers at all; they need different docs.
>>>>
> 
> which goes-on to be 'bang on the money' regarding @boB's frustration:
> <<<
> Updating the documentation to fix common misunderstandings would save
> time in the long run for users and the core team.
>>>>
> Python Software Foundation's Blog:
> https://pyfound.blogspot.com/2020/04/cpython-documentation-next-5-years.html
> 
> 
> NB perhaps I haven't paid sufficient attention, but I don't think that
> the proposed Python Steering Council workgroup called the "Documentation
> Editorial Board" has published much since.
> (but will be delighted to be corrected on this, directed to web.refs, etc)


eh, it's having some startup pains. I guess maybe too many people 
volunteered to help out? (I was one of them) and a few people were 
assigned onto the committee, and some other Python longtimers raised a 
stink because they felt they were getting left out when they had 
long-term experience with the docs.  Except, as dn has detailed here, 
those docs are currently oriented in a way that's known not to be 
helpful (enough) to many... so right now, something is going on, and we 
masses have no insight into it at all.

the note about cross-purposes is pretty valid anyway.  I'm working on a 
Python project where I'm trying to improve the way the 
generated-from-docstrings documentation renders when Sphinx is pointed 
at it.  That's not at all the same thing as how it renders when you call 
help().  Fortunately for _this_ case the code is such your not likely to 
open an interpreter and introspect into it that way, by calling help on 
things.  But it kind of highlights that when there are several possible 
consumers of the documentation, both groups of humans, and various 
tools, it is *really* hard to figure out how to present things.  Which I 
guess was the point of the included above... to think about how to do 
better.