Do you feel bad because of the Python docs?

[nn]

On Feb 26, 11:19 am, notbob <not... at nothome.com> wrote:
> On 2013-02-26, Steven D'Aprano <steve+comp.lang.pyt... at pearwood.info> wrote:
>
> > "The Python documentation is bad, and you should feel bad".
>
> Ahh!  A point at which I can interject.
>
> As a rank green python noob, I definitely hava an opinion on python
> documentation and it's not entirely flattering.  OTOH, it's hard to
> toss any other single linux based documentation up as a sterling
> example.  IOW, I've seen worse.  How am I learning about python?
>
> Several sources.  The "Non-Programmer's Tutorial" docs from wikibooks
> was a false start.  It goes for about 2 pages before I realized
> they've snuck in some python syntax without explaining it.  So, I jump
> over to "The Python Tutorial", which immediately leaves me submerged,
> as it's waaay over my clueless head.  I flounder around and
> desperately grab onto "Basic Python" over at About.com.  Finally, I'm
> rescued!
>
> Whoda thunk it?  I usta despise About.com.  But, they've matured
> greatly since their early days.  I'm not a programmer.  In fact I
> really dislike programming.  But, as a long time linux user, I really
> need to learn a useful higher language.  And here is this website that
> takes me by the hand and speaks to me like what I am.  Dumb as a post
> and disinterested.  But, they are patient.  They explain basic
> programming concepts before launching into specifics.  When they do
> get specific, they use simple examples that make sense.  The don't
> toss in syntax they haven't fully explained.  Great site and the one
> I'm now using to progress.  I'm sure the other sites I've named will
> become helpful, eventually, but now I can move forward with
> confidence.
>
> Are python doc sites perfect?  No.  I've yet to come upon anything
> that clarifies why's and wherefores and the differences between the CMI
> IDLE and the GUI IDLE.  And boy, are they different!  OTOH, as I said,
> I've seen worse Linux docs.  BitchX or zsh?  What docs!?  Even the man
> pages took me a long time to figure out.  Bluefish?  Krita?
> Puh-leeze!  emacs?  It's a wonder I can use it at all.  ;)
>
> Despite all that, I'd say python documentation is better than a poke
> in the eye with a sharp stick.  I'm sure the official pages will make
> more sense to me when I understand more.  As it is, they jes toss out
> "lc-letter" like I know what they're talking about.  They explain it a
> little bit, but I still hadda wiki it to get the full story.
>
> As a person with some technical writing experience, I know how
> difficult it can be.  I had to be careful about who I was writing for,
> engineers or laymen.  It's the same with programming docs.  Writing
> tutorials about python as if I jes came from 5 yrs as a C programmer
> is not in the least bit helpful to a beginner like myself.  Sometimes,
> one jes hasta hunt for the right flavor.
>
> nb

For me on the other hand. The Python tutorial has been the most useful
tutorial I have ever used. I had experience with Basic and Pascal.
Most other tutorials go too slow for me and I loose interest. The
python one just kept going and after reading the dozen pages in a
couple of hours I had enough of an idea about the language to start
doing the things I was interested in.

The only thing that confused me at first was finding functions like
"open" or "input" and string methods. I lost a bit of time searching
in the language reference until I found out that they are in the
Library reference: I didn't think of "open" as a library. But now I
have no problem; all I need is found under Library reference in
section 2 and 4 and starting with section 6. I also use the global
module index when I already have an idea what I am looking for.

What it could have is better searching capability and a way to see
more examples. Examples would clutter the documentation so maybe they
should be collapsible, but you can never have enough examples. As
Einstein said:
“Example isn't another way to teach, it is the only way to teach”
Outside of the tutorial there are not a lot of succinct examples of
more advanced uses of the different keywords and builtins. Thankfully
for the libraries there is Python Module of the Week for people that
know about it.