[docs] Python documentation well designed to confuse newbies

[YK]

I'm getting quite frustrated with this poorly designed documentation. Info
about a specific topic I'm interested in is usually split between 2 places,
if not 3. Which forces me to search the whole documentation for locations
where they were, which location had that specific part which I seek. Why
can't each topic simply be in one place? Documentation is so fragmented.
Any love for newbies? Whole documentation is a huge wreck, it should be
done over, with better details, explanations, examples and without
excess jumping. Have you seen how neat and tidy *w3schools* is?

Today I stepped on another landmine in Python's documentation. Was checking
out "*secrets — Generate secure random numbers for managing secrets*". At
some point of writing code, I wondered to myself, gee, why doesn't secrets
module simply have a shuffling function to shuffle object contents. So
instead I wrote a manual thing that picked items randomly into a new list.
Few days later, I accidentally stumbled upon a code piece on the internet: "
*secrets.SystemRandom().shuffle(obj)*". I again opened up secrets topic in
documentation. I could not see anything directly as that. Instead I have
not much telling info about a class and then "*See random.SystemRandom for
additional details.*". Alright, I'll click that. And again, info about a
class and nothing related to "*secrets.SystemRandom().shuffle(obj)*". But
that expression works. How? Why? No idea. Great. Checking in *Wing IDE*, I
noticed that it points to "*random.shuffle()*" instead. How, why are they
related? I have no idea. How am I, as a non-expert to Python, supposed to
know and understand this feature? Documentation is poorly designed, I will
soon have a hole in my front of my head from rubbing out of frustration. Is
the documentation designed so on purpose? Do I have to hand out a 3 digit
figure of cash to go to Python school? Python is free, so why can't proper
education about Python be free too...
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20190404/d05428ee/attachment.html>