Python documentation too difficult for beginners

[Cameron Simpson]

On 02Nov2010 03:42, jk <sanjo_ie at yahoo.com> wrote:
| I've been coding in PHP and Java for years, and their documentation is
| concise, well structured and easy to scan.

While I agree about Java, at least the core Java docs, and javadoc
output in general (_great_ cross referencing!) I have mixed feelings
about the PHP docs. Though I suspect that stems from a dislike of the
PHP library API in general more than the docs, perhaps.

| Others have mentioned this apparently for years (see:
| http://stackoverflow.com/questions/4046166/easy-to-navigate-online-python-reference-manual/4070851
| and http://www.russellbeattie.com/blog/python-library-docs-still-suck
| and http://xahlee.org/perl-python/xlali_skami_cukta.html).
| 
| Compare for instance the differences in ease of use, and speed of use,
| of these:
| 
| http://docs.python.org/library/functions.html#open
| http://uk.php.net/manual/en/function.fopen.php
| 
| The former is difficult to find (try searching for 'open' in the
| search box and see what you get).

I confess I almost never use the search box - as you say the result
relevance can be dodgy.

However, I do find the docs easy to use and pleasant to read on the
whole. My use is as follows:

  For speed and convenience I have the docs locally stored.

  I open the front page and then usually both the modules and index in
  adjacent brwoser tabs.

  I go to the index if I'm not sure of the module.

The strength of the index is that it tends to contain stuff that people
thought should be indexed (versus searches, which often have no
contextual understanding of the text, so their relevance is weaker).
The weakness of the index is that it can be hard to pick the relevant
entry. Open-link-in-new-tab is my friend here:-(

| It is simply a collection of
| paragraphs without strong enough contrast to differentiate the
| different parts - parameters, parameter values, return types,
| exceptions and related functions. It is slow to read and doesn't allow
| easy visual scanning.

That is true (the scanning). But by contrast, it does read like prose
and lends itself to a visit that gets you a complete feel for the
function.

[...]
| Has anyone else struggled while trying to learn the language? The
| whole documentation system seems geared towards people who already
| know what they're looking for and is close to useless for beginners.
| I'm not the only one who finds google an easier way to find
| documentation about python.

I certainly don't find the core docs hard to use (with some exceptions;
I still don't really understand the urllib stuff for the cases where
configuration is needed - weird proxy setups etc).

I've only been using Python for a few years and have generally found
that language easy to learn and the docs easy to read. I rarely reach
for The Google unless I'm seeking examples; the docs could do with a few
more of these IMHO.

I understand the attraction of the structured layout javadoc yields but
find it leads to "drier" documentation. It also works well for Java
because it is strongly typed - a great deal of the structure in the docs
can come directly from the code because argument counts, names and types
are always explicit (or deducable).

These are just initial responses. Now to wade the whole thread:-)
-- 
Cameron Simpson <cs at zip.com.au> DoD#743
http://www.cskk.ezoshosting.com/cs/

On the contrary of what you may think, your hacker is fully aware
of your company's dress code. He is fully aware of the fact that it
doesn't help him to do his job.
- Gregory Hosler <gregory.hosler at eno.ericsson.se>