3 ms·
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 some
by faraggi 10y ago
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.
- Flimm 10y agoI 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.
- hjnilsson 10y agoThe 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.