Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Python documentation too difficult for beginners

Reply
Thread Tools

Python documentation too difficult for beginners

 
 
jk
Guest
Posts: n/a
 
      11-02-2010
Hi,

I've been coding in PHP and Java for years, and their documentation is
concise, well structured and easy to scan.

Others have mentioned this apparently for years (see:
http://stackoverflow.com/questions/4...manual/4070851
and http://www.russellbeattie.com/blog/p...ocs-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). 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.

The latter has clearly delineated, standardised content areas for each
of these without excessive text. It uses tables which are easy to scan
for possible opening modes and allows users to contribute their own
examples.

Sadly, the use of restructured text by python doesn't allow a new
document generator to be written - all existing documentation would
need updating with docblocks or something similar.

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.

Is there much chance that the Python maintainers will change their
documentation system to make it more like Java or PHP? How would I go
about trying to make that happen?
 
Reply With Quote
 
 
 
 
jk
Guest
Posts: n/a
 
      11-02-2010
This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
about.

Why aren't the official docs like this, and why has it taken me 2 days
of searching? All this needs is a search engine behind it and it'd be
perfect.
 
Reply With Quote
 
 
 
 
Tim Wintle
Guest
Posts: n/a
 
      11-02-2010
On Tue, 2010-11-02 at 04:23 -0700, jk wrote:
> This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
> about.

Aaaarrrgggghhhh

> Why aren't the official docs like this,

Because not everyone likes documentation like that. Personally I far
prefer the existing documentation to the JavaDoc-style link you sent.

> and why has it taken me 2 days of searching?
> All this needs is a search engine behind it and it'd be
> perfect.


Personally I use Google, e.g.

"list site:docs.python.org"

to bring up documentation about the list type.





 
Reply With Quote
 
Tim Golden
Guest
Posts: n/a
 
      11-02-2010
On 02/11/2010 11:23, jk wrote:
> This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
> about.
>
> Why aren't the official docs like this, and why has it taken me 2 days
> of searching? All this needs is a search engine behind it and it'd be
> perfect.


I'm glad you find the epydoc format useful. And I'm glad that various
people have taken the trouble to produce documentation for Python in
various formats that suit them. But why do you imagine that the core
Python documentation -- developed and maintained by a group of people
who clearly have some idea what they're doing -- should change to a
format which happens to suit you?

The Python documentation source and the source code of Python itself
are all freely available. Any initiative by you or by others to
produce alternative, possibly searchable and commentable, versions of
them would I'm sure be welcomed by many. But not everyone finds, eg,
the PHP style of user annotation helpful. Not everyone likes epydoc
output: I don't myself.

In short, please feel free to contribute directly to the core
documentation effort, or to produce alternatives yourself and to
advertise them here or elsewhere within the Python community. But
please don't come along and say "Why aren't the Python docs like
<this other thing> which happens to suit me better?"

TJG
 
Reply With Quote
 
Martin P. Hellwig
Guest
Posts: n/a
 
      11-02-2010
On 11/02/10 10:42, jk wrote:
<cut>
> Is there much chance that the Python maintainers will change their
> documentation system to make it more like Java or PHP? How would I go
> about trying to make that happen?

I am by no means an authority however since you ask it here I feel
compelled to give you my opinion

In general I would think that more documentation is always welcome, if
you feel like you can make a contribution, excellent, please do!

However, I found that the documentation available was enough for me, and
I didn't even have to go to the googles for that.

Typing help(thing_i_want_info_of) in the interpreter gives me precise
consistent information for what I need to do with whatever it is I am
doing and yes that is largely a replication of what is mentioned on the
site itself (well more the other way around actually).

In the odd cases this doesn't help me, I google for examples.
If that doesn't help I look at the modules __file__ and open that module
to read the source.

And when I started 10 odd years ago with Python it was my first language
with no prior confusion of other languages, since then I extended my
knowledge with C and assembler but on a day to day basis I still use Python.

--
mph

 
Reply With Quote
 
Antoine Pitrou
Guest
Posts: n/a
 
      11-02-2010
On Tue, 2 Nov 2010 04:23:49 -0700 (PDT)
jk <(E-Mail Removed)> wrote:
> This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
> about.
>
> Why aren't the official docs like this, and why has it taken me 2 days
> of searching?


What's wrong with this:
http://docs.python.org/library/
?

If you have specific ideas for improvements, you can open issues at
http://bugs.python.org.

Thank you

Antoine.


 
Reply With Quote
 
jk
Guest
Posts: n/a
 
      11-02-2010
On Nov 2, 11:49 am, Tim Golden <(E-Mail Removed)> wrote:
> But why do you imagine that the core
> Python documentation -- developed and maintained by a group of people
> who clearly have some idea what they're doing -- should change to a
> format which happens to suit you?


It's not just me who's found the current documentation frustrating.
And sure, the developers know how to code, but they probably can't see
the project with the eyes of a beginner any more.

Making a change to how code is documented to allow more javadoc-style
documentation to be produced could help people migrate from a java
background and ease the learning curve for them, leading to wider
adoption of the language. It wouldn't necessarily mean that the
current documentation style would need to change either.

> In short, please feel free to contribute directly to the core
> documentation effort, or to produce alternatives yourself


I may well do that.

@Tim Wintle
> Personally I use Google, e.g.
> "list site:docs.python.org"
> to bring up documentation about the list type.


Surely you shouldn't have to go to google though? Or the interpreter?
Maybe it's just what you're used to, but I'd expect the language's web
site to provide enough of a reference in itself, while using google
for examples.
 
Reply With Quote
 
Steven D'Aprano
Guest
Posts: n/a
 
      11-02-2010
On Tue, 02 Nov 2010 03:42:22 -0700, jk wrote:

> Hi,
>
> I've been coding in PHP and Java for years, and their documentation is
> concise, well structured and easy to scan.


Well, that's one opinion.


> Others have mentioned this apparently for years (see:
> http://stackoverflow.com/questions/4...vigate-online-

python-reference-manual/4070851
> and http://www.russellbeattie.com/blog/p...ocs-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).


A fair point -- the built-in open comes up as hit #30, whereas searching
for open in the PHP page brings up fopen as hit #1. But the PHP search
also brings up many, many hits -- ten pages worth.

But in any case, the Python search functionality could be smarter. If I
had a complaint about the docs, that would be it. Fortunately, I have
google


> 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.


It's *nine* paragraphs, three of which are one-liners, the longest of
which is eight lines. If you have trouble reading that, well, you have a
problem. The PHP docs for fopen are FIFTY-EIGHT paragraphs.

Okay, okay, I was unfair. I counted section headings as separate
paragraphs. A more reasonable count is... twenty-six paragraphs, tables,
sections and subsections. Plus *dozens* of user-contributed recipes, bug
reports, tricks, tips and comments. And you call this concise???

Reading the docs, I'd say that PHP needs all this extra documentation
because it's so much more complicated. fopen has all this implicit magic
behaviour that needs documenting -- it will try to guess a scheme from
the file name, if it can't guess the scheme it will guess that it's a
local file, and the behaviour depends on various globals. In comparison,
Python's open is very simple: it only opens files. No wonder Python's
docs are simpler.

The PHP docs felt it necessary to give a warning *three times*, one after
the other, about using binary mode when opening files. Apparently once
was not enough.

The Description subsection of the PHP fopen doc says:

fopen() binds a named resource, specified by filename, to a stream.

What's a stream? So I read, and read, and read, and eventually, almost at
the bottom of the official docs, I find the section "Return Values":

Returns a file pointer resource on success, or FALSE on error.

Great! Now, what's a file pointer resource, and how does it differ from a
stream? No idea.

Contrast that with the Python docs. In the *very first sentence*, it says:

Open a file, returning an object of the file type described in
section File Objects.

with both "file" and "File Objects" being hyperlinks to the appropriate
part of the docs. I think I'll stick with the Python style, thank you
very much.


> The latter has clearly delineated, standardised content areas for each
> of these without excessive text. It uses tables which are easy to scan
> for possible opening modes and allows users to contribute their own
> examples.


There has been discussion on python-dev about user contributed examples.
The pros are that users can add tricks and tips. The cons are that,
without constant attention, the user-contributed content will grow old
and stale, or worse, be filled with nonsense.

However, there is a Python wiki. It doesn't get anywhere near as much
love as it deserves, and (I think) the consensus was that the official
Python docs should stay official, but link to the wiki for user-
contributed content. This hasn't happened yet.

http://wiki.python.org/moin/


> Sadly, the use of restructured text by python doesn't allow a new
> document generator to be written - all existing documentation would need
> updating with docblocks or something similar.
>
> 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.


Why do you think this is a bad thing? The Python docs are the reference
manual, not a tutorial. Quite frankly, if I were a PHP developer, I'd be
pretty annoyed at having to read this in the docs for fopen:

If you use the wrong line ending characters when writing your
files, you might find that other applications that open those
files will "look funny".

Gosh, really? Thanks for the tip, Captain Obvious.

It's always difficult to know how much information is too much. The PHP
docs seem to take an "everything including the kitchen sink" approach.
Given that approach, it makes sense to divide everything into
subsections, one page per function. But with Python's minimalist
approach, it would just be annoying. Compare the four lines of:

http://docs.python.org/library/functions.html#id

with this re-write in the PHP fashion:


=====
id
=====
(Python 1.x, Python 2.x, Python 3.x)

id -- id of an object


Description
-----------

id(object)

id returns the numeric "identity" of an object, which is guaranteed to be
unique and constant for this object during its lifetime.

Note: two objects with non-overlapping lifetimes may have the same id()
value.

Note: CPython implementation detail: This is the address of the object.


Parameters
----------

* object

Any object.

Note: all data in Python are objects, even ints and strings.

Note: there are no undefined objects in Python. If you call
id(variable) on an unbound variable name, Python will raise an
exception.

Return values
-------------

Returns an integer or long integer object representing the ID of the
argument.


Errors/exceptions
-----------------

If the argument to id() is a named variable rather than a literal, and
that name is not bound to any object, then a NameError will be raised.
Otherwise every call to id() must succeed.

Note: if the call to id() is inside a function, the exception may be a
subclass of NameError such as UnboundLocalError.

Note: literals are not guaranteed to always refer to the same object.


Changelog
---------

0.9 First version added (I think).


Examples
--------

id(x)
id(alist[1])
id(instance.attribute)
id(module.name.attribute['key'].method(arg1, arg2).seq[2])


Notes
-----

If you're still reading, I admire your persistence.


See also
--------

Python's object model
Exceptions




> Is there much chance that the Python maintainers will change their
> documentation system to make it more like Java or PHP? How would I go
> about trying to make that happen?



Unlikely. You could raise the issue on the python-dev list, or see if
there is a SIG mailing list specifically for the docs.

Frankly, I think that the best thing you could do is start a fork of the
docs and see if you get any interest from people. If you do, then you can
go back to python-dev with proof that there is a genuine popular desire
for more structured, PHP-style documentation.


--
Steven
 
Reply With Quote
 
jk
Guest
Posts: n/a
 
      11-02-2010
On Nov 2, 1:42*pm, Steven D'Aprano <st...@REMOVE-THIS-
cybersource.com.au> wrote:
> It's always difficult to know how much information is too much. The PHP
> docs seem to take an "everything including the kitchen sink" approach.
> Given that approach, it makes sense to divide everything into
> subsections, one page per function. But with Python's minimalist
> approach, it would just be annoying. Compare the four lines of:
>
> http://docs.python.org/library/functions.html#id
>
> with this re-write in the PHP fashion:
>
> =====
> id
> =====
> (Python 1.x, Python 2.x, Python 3.x)
>
> id -- id of an object
>
> Description
> -----------
>
> id(object)
>
> id returns the numeric "identity" of an object, which is guaranteed to be
> unique and constant for this object during its lifetime.
>
> Note: two objects with non-overlapping lifetimes may have the same id()
> value.
>
> Note: CPython implementation detail: This is the address of the object.
>
> Parameters
> ----------
>
> * object
>
> * Any object.
>
> * Note: all data in Python are objects, even ints and strings.
>
> * Note: there are no undefined objects in Python. If you call
> * id(variable) on an unbound variable name, Python will raise an
> * exception.
>
> Return values
> -------------
>
> Returns an integer or long integer object representing the ID of the
> argument.
>
> Errors/exceptions
> -----------------
>
> If the argument to id() is a named variable rather than a literal, and
> that name is not bound to any object, then a NameError will be raised.
> Otherwise every call to id() must succeed.
>
> Note: if the call to id() is inside a function, the exception may be a
> subclass of NameError such as UnboundLocalError.
>
> Note: literals are not guaranteed to always refer to the same object.
>
> Changelog
> ---------
>
> * 0.9 *First version added (I think).
>
> Examples
> --------
>
> * *id(x)
> * *id(alist[1])
> * *id(instance.attribute)
> * *id(module.name.attribute['key'].method(arg1, arg2).seq[2])
>
> Notes
> -----
>
> * *If you're still reading, I admire your persistence.
>
> See also
> --------
>
> * *Python's object model
> * *Exceptions
>
> Steven


You're right in that the python docs in this case are less lines, but
that's one of the problems. It doesn't mention anywhere the extra
detail you've added regarding exceptions thrown. That's the kind of
thing that probably comes through experience or some kind of
convention which isn't obvious to beginners. Having things split into
sections - parameters, return types, exceptions, etc - lets me find
what I'm looking for quickly.

As for the 9 paragraphs statement, there's a usability book that
applies here - it's called "Don't make me think". I shouldn't have to
go through freeform text to find what I'm looking for when a list
would make that information easier to find. And splitting the docs
into sections would allow me to skip to what I'm looking for. I really
would be much happier with your example documentation.

I think the key difference is that I don't want to have to *read* the
python docs - I want to be able to scan for what I'm looking for and
find it easily. That makes me productive.
 
Reply With Quote
 
Paul Rudin
Guest
Posts: n/a
 
      11-02-2010
Steven D'Aprano <(E-Mail Removed)> writes:

> A fair point -- the built-in open comes up as hit #30, whereas searching
> for open in the PHP page brings up fopen as hit #1. But the PHP search
> also brings up many, many hits -- ten pages worth.
>


OTOH googling for "python open" gives you the correct (for 2.7) page as
hit #1 - although you then have to use your browser's "find" facilty to
actually get to the description of the function in question.
 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
converting XSD documentation to HTML documentation kev.sully@gmail.com XML 1 09-16-2006 12:09 PM
Java Interview Questions: Am I Being Too Difficult? Spammay Blockay Java 69 04-15-2006 04:08 AM
Python documentation: How about structured documentation? Looking for comments/suggestions Kenneth McDonald Python 2 05-06-2004 04:11 AM
Principles of documentation (was: Python Documentation Blows!) Cameron Laird Python 1 04-03-2004 06:54 PM
absolute beginners question about API documentation Markus Joschko Python 7 07-06-2003 08:43 PM



Advertisments