Hacker News Reader

Comment by faraggi | Hacker News Reader

I see many people like python docs, and I agree, but the article talks about the difficulty for __beginners__.

That being said, maybe the python docs need something equivalent of wikipedia's 'Simple English' definitions.

Maybe by adding a 'simple' prefix (ie: simple.docs.python.org/3.5/library/re.html) that takes us to the very simplified version of the current documentation. Links to the in-depth docs are obviously necessary as well.

View on HN

The main problem with the python docs is not the verboseness. It's that they are entirely unstructured. If there just was a standard list of bold parameter - explanation and finally return value it would help immensely.

My own favorite is urllib.request.urlopen, the description mixes arguments, return values and exceptions in a blob of text two pages long. It's very confusing to read if you are a beginner just trying to fetch a file. The examples are way, way down on the page where you will never find them, the table of contents is so long you can't even see there is an example section unless you scroll down the menu.

On the bright side though, everything is explained in the text. It just less accessible than some other projects' documentation.

I don't think he's advocating for shortening the docs, if you look at the example he gave, his improved version was much longer: it explained each argument in detail as well as the return type, and gave an example.

Reply on news.ycombinator.com