Python Documentation (should be better?)

[Christopher J. Bottaro]

Sébastien Boisgérault wrote:

> 
> "Manual" == scope of the *Lib Reference* + informal style of the
> *Tutorial*,
> 
> Right ?

Yes!  That sounds good.  "Informal style" yes, but "tutorial style" no.  I
shouldn't be there to teach like the tutorial, but for reference.  And of
course, the manual shouldn't cover the modules like the lib reference does,
but just the language itself and "built in" types.

Ok, here is a concrete example of what I like about the PHP manual and what
people I know have had a hard time with Python.  Go to the PHP manual page. 
Type "array" in the search input field.  It comes back with a page that
briefly describes arrays in PHP and then lists all the functions that have
to do with arrays.

Contrast that with Python.  First off there is no "search" mechanism built
into the documentation page (yes I know you can google it, but that just
doesn't feel right).  Second off...well, my argument sucks because I
apparently I haven't looked at the Python tutorial recently.  But before,
if you looked up "lists" in the tutorial, you got a tutorial style page on
them.  If you wanted to see their methods, you had to completely back out
of the tutorial, go to the library reference, then find the section on
"mutable sequences".  How unintuitive is that?  But like I said, the
tutorial is better now.  It lists the methods on list and there is a link
in the dictionary section to the "mapping types" section in the library
reference.

Oh well, I guess all is well.

-- C

> Consider non-official manuals such as:
>     + http://diveintopython.org/toc/index.html (free)
>     + python in a nutshell
>     + python cookbook
>     + etc.
> 
> Cheers,
> 
> SB
>