[docs] Python documentation well designed to confuse newbies

[Julien Palard]

Hi anonymous, thanks for your feeback!

> Why can't each topic simply be in one place?

That's because there's multiple levels of details, take typically:

- https://docs.python.org/3/tutorial/controlflow.html#for-statements
- https://docs.python.org/3/reference/compound_stmts.html#the-for-statement

those are describing the exact same thing, but with different level of detail.

A newcomer don't want the level of detail given by reference/, but after a few years may start to be interested about those details, so it's simply split to multiple places to give to one only what's matter.


> Today I stepped on another landmine in Python's documentation

This is the exact moment you should tell yourself "let's fix this", and open a pull request on github (to add a paragraph or simply a link from a page to another in this case), to make content more discoverable.

I alone am not able to find all those little possible improvements, but if anyone while finding a "landmines" fixes it, the doc becomes better over time, and this is what's already happening, there's on average one edit per day on the documentation to enhance it.

You know, after reading that doc for 15 years, and translating it for like 5 years, I can navigate thrue it and read it blindfolded, so it really takes new pairs of eyes like yours to spot those little improvements, just come and help :)

Bests,
-- 
Julien Palard
https://mdk.fr