«

On 2013-02-26, Andrew Berg <> wrote:
> On 2013.02.26 10:19, notbob wrote:
>> zsh? What docs!?
> You mean other than the gigantic user manual?
> http://zsh.sourceforge.net/Doc/

"This document was generated by Simon Ruderich on July 24, 2012"

.....'bout damn time!!

nb

On 2013-02-26 17:54, notbob wrote:
> >> zsh? What docs!?
> > You mean other than the gigantic user manual?
> > http://zsh.sourceforge.net/Doc/
>
> "This document was generated by Simon Ruderich on July 24, 2012"
>
> ....'bout damn time!!

Generated...from source that has been around for ages:

http://zsh.git.sourceforge.net/git/g...51502cb2;pg=11

which suggests that they've been actively maintained since 1999-2000
or so.

-tkc

On 2013-02-26, Tim Chase <> wrote:

> which suggests that they've been actively maintained since 1999-2000
> or so.

.....in various guises, dating back to the man pages. Not all as
thorough as the latest "manual". Perhaps I shoulda qualified usable
docs.

nb

On 2/26/2013 7:54 AM, Steven D'Aprano wrote:
> One week ago, "JoePie91" wrote a blog post challenging the Python
> community and the state of Python documentation, titled:
>
> "The Python documentation is bad, and you should feel bad".
>
> http://joepie91.wordpress.com/2013/0...tation-is-bad-
> and-you-should-feel-bad/

To me, this is a lying troll rant worth less than most of RantingRick's
posts.

> It is valuable to contrast and compare the PHP and Python docs:
>
> http://php.net/manual/en/index.php
> http://www.python.org/doc/

The contrast has been discussed before on python-list and even pydev. To
repeat: in my opinion, and that of most core developers, the python docs
are superior. It is Joe's lie to equate difference of opinion with
indifference.

Python has a nice Tutorial for beginners. It is an integral part of the
doc set. To ignore that (and the indexes) in discussing the usability of
Python docs by beginners is to lie. (If beginners who actually read the
tutorial have problems with particular paragraphs, improvements can be
and have been made.)

Examples: Once startup is explained, the rest of the tutorial is about
half text and half example. I think that is a good balance. Anyone who
reads the tutorial knows how to call a function. I think doubling the
size of the Library *Reference* with trivial, repetitive examples like:

>>> len([1,2,3])
3

would be a negative for reference use*. Python has a super-duper
interactive mode for trying things like this oneself, and that teaches
*better* than just reading the same thing. (And if the tutorial never
discusses len() and its generic use for all concrete collections, it
should.)

* Anyone who disagrees can go to
http://www.lightbird.net/py-by-examp...functions.html
where you can find that and other examples for builtins and about 30
modules. Actually, I can imagine that some beginners would benefit from
this page as an extension of the tutorial. This site may be an outcome
of the previous discussion, which more or less ended with the fact that
anyone who wanted to produce php-style Python docs was free to do so.

Searching: it is true that the Python docs are written for being read by
people, rather than by search engines#. It has a hand-crafted index
(yes, it still needs patches) that will get you most places, especially
for anyone who has read the tutorial to get the basics. For 'length of a
list' one can find 'len() (built-in function)' and find that 'len'
indeed mean length and, more generally, size.

# Anyone who wants to could develop an seo-optimized python-by-function
website that goes into exquisite details for each function on a separate
page.

len(collection) => count
Built-in function len() allows one to find the
* length or size of a list
* length or size of a tuple
* length or size of an array
* length or size of a string
* length or size of a bytes
* length or size of a bytearray
* length or size of a memoryview
* size of a set
* size of a frozenset
* size of a dict or dictionary
* size of dict view
* size of user-defined collecton class instances

Returns 0 for empty collections. Raises TypeError for inputs that are
not collections or that do not support len() calls, because they do not
have a properly written .__len__ methods.

If I were involved, I would *not* junk-up such pages with random user
posts. Anything worth being added should be incorporated into the entry
itself.

--
Terry Jan Reedy

On Tue, Feb 26, 2013 at 11:38 AM, Adam W. <> wrote:
> I think learning a language from the documentation is an unreasonable expectation and burden for the authors.

That's how I learned it. The Python tutorial, together with the stdlib
reference manual, are often recommended to beginners to Python in
order to learn it. The combination of the documentation and consulting
other programmers helped me learn the language just fine.

> Buy a book, take a class, they are designed to provide you with a path from start to finish in a sensible manner, the documentation in my opinion is supposed to be a reference and a refresher with an assumed level of basic fundamentals.

I would assert it isn't very kind to those even with basic fundamentals.

For example, under precisely what circumstances does int() raise
TypeError? You won't find that under either int's documentation, or
TypeError's documentation, you have to look it up under __int__, which
is _not_ a basic fundamental. And rather than helping you along the
way, the documentation for int() actively misleads you by its
implicature that the only acceptable types are strings, ints, and
floats. And then even if you have the foresight to remember "oh yeah,
isn't there a special method for this?", you have to find the
documentation for __int__, which is itself is three quarters of the
way down this massive page:
http://docs.python.org/2/reference/datamodel.html .

-- Devin

On 02/26/2013 07:54 AM, Steven D'Aprano wrote:
> One week ago, "JoePie91" wrote a blog post challenging the Python
> community and the state of Python documentation, titled:
>
> "The Python documentation is bad, and you should feel bad".
>
> http://joepie91.wordpress.com/2013/0...tation-is-bad-
> and-you-should-feel-bad/
>
> It is valuable to contrast and compare the PHP and Python docs:
>
> http://php.net/manual/en/index.php
> http://www.python.org/doc/
>
> There's no doubt that one of PHP's strengths, perhaps its biggest
> strength, is the good state of documentation. But should we feel bad
> about Python's docs? I don't think that either the Python documentation
> or community is as bad as JoePie91 suggests. (Well, I won't speak for
the
> people on Freenode's #python. It took me approximately three minutes to
> be banned from there, with no warning or explanation.)
>
> Another response to the blog post, by one of the core developers:
>
> http://blog.briancurtin.com/posts/wh...el-so-bad.html
>
>
>


I think the issue with python documentation is that it ignores the 95/5
rule: 95% of people who land on a module's page are only looking for 5%
of its information. So ideally it'd be separated in two different pages
or two sections of the same page, something like:

================================================== =============================================

Hi, chances are you are the 95% of people who isn't interested in the
intricacies, obscure edge cases et cetera. Here are the few common use
cases for this module:

....

....

....

================================================== =============================================

Hi, the section above obviously did not suit your needs, so you must be
in the 5% who has no choice but to either read through or at least
glance through, or use search, to find what you need in the following
umpteen million of screenfuls:

.... * 1000000


================================================== =============================================

Why doesn't Python do that? Quite simply, it's a lot more work: you have
to separate most useful parts from the rest, which involves judgement
calls and will cause some disagreement and ultimately won't be perfect.
Once done, two separate sections need to be mainained and kept in sync.
It's important that they don't contradict each other.

Right now places like SO and mailing list act like the first section I
described. The issue is that they're not always up to date and not
guaranteed to be correct, are not in a consistent style and depth, are
not centralized.

-m


--
Lark's Tongue Guide to Python: http://lightbird.net/larks/

Is life not a thousand times too short for us to bore ourselves?
Friedrich Nietzsche

On Feb 26, 11:19*am, notbob <not...@nothome.com> wrote:
> On 2013-02-26, Steven D'Aprano <steve+comp.lang.pyt...@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.

On 26 Feb 2013 12:54:56 GMT
Steven D'Aprano <steve+> wrote:

> One week ago, "JoePie91" wrote a blog post challenging the Python
> community and the state of Python documentation, titled:
>
> "The Python documentation is bad, and you should feel bad".

No I do not feel bad.
I did not read the post either.

As a newcomer to python I found the docs to be difficult.
I'm getting used to reading them after a few months.
Any document is written for some audience, maybe
python needs to target wider audience groups. One for programmers
from other languages (maybe one for each major language?).
One for those new to programming and python at the same time.
One for python programmers (have mostly that now, I think)
Etc.

If I harken back to those days when I first used man pages
it was a moment of "Wow! This is great!" followed by many
moments of "Hmmmm, do they mean this...?".

Incorrect docs are worse than none. I think most of the python docs
I've read have been correct although sometimes stuff is just missing.
Like threading.local was not easy to find.

HTMLParser is avoided by lots of people because it requires lots
of prior knowledge.

Examples are worth more then plain old doc.

On 26/02/2013 12:54, Steven D'Aprano wrote:
> One week ago, "JoePie91" wrote a blog post challenging the Python
> community and the state of Python documentation, titled:
>
> "The Python documentation is bad, and you should feel bad".
>
> http://joepie91.wordpress.com/2013/0...tation-is-bad-
> and-you-should-feel-bad/
>
> It is valuable to contrast and compare the PHP and Python docs:
>
> http://php.net/manual/en/index.php
> http://www.python.org/doc/
>
> There's no doubt that one of PHP's strengths, perhaps its biggest
> strength, is the good state of documentation. But should we feel bad
> about Python's docs?

I strongly disagree with most of what the author writes. To start with,
there's this:

Let’s start out with a simple example. Say you are a developer that
just started using PHP, and you want to know how to get the current
length of an array. You fire up a browser and Google for “PHP array
length sitehp.net�. The first result is spot-on, and one minute
later, you know that count($arr) will suffice.

Now let’s say that you wish to do the same in Python. In this case,
you would Google for “Python list length site:docs.python.org�, and
the first result is… a page with several chapters on standard types?

It seems to me that this is /completely/ the wrong way for a developer
who's new to Python to go about learning the language. If you don't know
enough Python to be familiar with len(), the sensible thing to is not to
try coding by finding out individual language features as and when you
need them, but to read the tutorial, systematically from start to
finish. This list is continually being bombarded with questions from
people who tried the former only to become stuck when something didn't
work the way they thought it should (I've been guilty of this too),
because knowing vocabulary is not the same thing as knowing how a
language works. The majority of such questions could have been answered
by simply reading the tutorial. More still could be answered by reading
the language reference, which really isn't very long.

That's not to say that experienced users don't need to look things up,
but then why would one restrict a web search to docs.python.org? Almost
every question I've had about how to do something in Python has already
been asked at StackExchange, and Google will find it.

When you Google for something, you will end up on a page that
explains a lot of things, including what you’re looking for. But how
are you supposed to know where on the page it is, or whether it’s
even on the page at all? The problem here is that the particular
operation you are trying to find documentation on, does not have its
own page.

And the solution is Ctrl-f.

The general norm for the Python community appears to be that if you
are not already familiar with the language, you do not deserve help.
If you do something in a less-than-optimal way, other Python
developers will shout about how horrible you are without bothering to
explain much about what you did wrong. When you ask out of curiosity
how a certain thing works, and that thing is considered a bad
practice, you will get flamed like there’s no tomorrow – even if you
had no intention of ever implementing it.

This is not my experience at all. Even when asking questions that I
could have answered myself if I had RTFM, I've received helpful advice
and nothing that could be construed as a flame. I don't know how this
compares to other programming language communities, but it's much
friendlier to newcomers here than, say, sci.math (whose competent
regulars are understandably suspicious of people asking idiotic
questions, given how many of those people turn out to be cranks).

PHP solves [ambiguity] by having examples for every single function
and class. If you’re not sure what is meant with a certain sentence in
the description, you just look at one of the included examples, and
all ambiguity is removed. It’s immediately obvious how to use things.

Python solves this by having an interactive interpreter. The tutorial
goes to the trouble of pointing out that "[i]t helps to have a Python
interpreter handy for hands-on experience".

If you are an experienced developer, then you are most likely in a
very bad position to judge how beginner-friendly the documentation
for a language is.

[...]

Most of all, accept that your personal experiences with Python, as an
experienced developer, are not worth very much. Listen to the newbies
when they tell you the documentation is hard to read or find stuff in.

But I'm not an experienced developer. I'm an amateur hobbyist who came
to learn Python having only had any real programming experience with BBC
BASIC and OPL (both as a child). I read the tutorial, then I read the
language reference, now I'm reading the library reference. They're all fine.


--
I have made a thing that superficially resembles music:

http://soundcloud.com/eroneity/we-be...-own-crapiness

Just to throw in my 2c -- in the same way that 'a picture is worth a
thousand words', an interactive interpreter is worth volumes of
documentation (especially one with such a nice help()/__doc__
functionality). It's worth pointing out that 'interpreter' appears in the
original rant once (according to ctrl-F, whole thing was tl;dr):

Want to know how the Python interpreter deals with input Y? Read the
source. And so on, and so on.

Not: "Open up an interpreter and input Y"

You aren't sure what errors are thrown by a particular function? Fire up
an interpreter and feed the function junk. You'll get your answer faster
than you can Google, and often learn neat stuff along the way. (I recall
one of RR's posts that actually had some good tips to
learn-via-interpreter).

Also, I'll bet the way I learned Python effectively would seem like
nails-on-a-chalkboard to others -- and vice versa. The 'one-size-fits-all'
doesn't work for documentation. Complete and concise often battle, with no
clear winner.

And his representation of the Python community does not appear to be
representative of my experience (threads begun via trolling rants
notwithstanding). But he's ranting on his blog; not a big deal really.

--Jason