473,583 Members | 2,875 Online
Bytes | Software Development & Data Engineering Community
+ Post

Home Posts Topics Members FAQ

Python Documentation (should be better?)

This post is just the culmination of my thoughts and discussions with my
coworkers on Python. If you are not interested, please skip over it.

At my work, we are developing a product from scratch. It is completely
modular and the modules communicate via SOAP. Because of that, we can
implement individual modules in any language of our choosing (so long as
they have good SOAP libs). I chose to do all mine in Python because I'm a
huge Python fan boy. Naturally, I tried to get my coworkers to try Python.
I made an agreement with one: I write one of my modules in PHP and he will
write one in Python.

After we were done, we talked about the pros and cons of the languages.
Funny, the con of Python (documentation) is PHP's strong point. The PHP
manual is extremely easy to navigate and its search feature works great.
Contrast that with Python, where you have to use "the tutorial" as the
manual. Also, the tutorial is just that...a tutorial, its a NOT a manual.
Its not organized like a manual and its not comprehensive like a manual,
hell, raw_input() isn't even mentioned in Chapter 7. Input and Output.

Now for the real kicker. Some of the module documentation doesn't even list
simple use cases or even the entire API. When my coworker came to me with
this complaint, my response was "oh, just load the interpreter, import the
module and call dir() on it. Then instantiate some objects and call dir()
on them also". My infatuation with Python had kept me from realizing the
sheer ridiculousness of that method to learn to use an API. Needless to
say, my coworker's reaction to that statement snapped me out of it. But
its the truth. How many of you learn a module by starting the interpreter
and "playing" around with it and using dir()?

The next complaint isn't really about documentation. Why isn't there a CPAN
or PEAR for Python? So many times I've search for a module, not found it,
started to write it myself, then later stumble across it on Google...ugh!

Don't get me wrong, I love Python. The language itself is second to none (I
haven't tried Ruby yet), but this experience has left me wondering about
the future success of Python. Even I, a huge Python advocate, has started
to use PHP more often simply because I can find well documented,
semi-official modules very easily and learning PHP is a breeze with the
awesome PHP manual.

What do yall think?

Jul 19 '05 #1
24 2207
I think Python's doc really rock. It's odd, why do you refer to the
tutorial when the lib API is what I'd consider "the docs".

If you're using Windows, then the doc browser included is pretty good
too...

Jul 19 '05 #2
Christopher J. Bottaro wrote:
[...]
Funny, the con of Python (documentation) is PHP's strong point.
The PHP manual is extremely easy to navigate and its search feature
works great. Contrast that with Python, where you have to use "the
tutorial" as the manual. Also, the tutorial is just that...a tutorial, its a NOT a manual.
The tutorial is great IMHO and yes, it is definitely not a
reference guide. But what's wrong with the online library
reference or its pdf equivalent ? And why don't you use the
python.org "search" (top right of the screen) ?
Now for the real kicker. Some of the module documentation doesn't
even list simple use cases or even the entire API.
Sometimes the 'missing' interface is (superficially) hidden
on purpose. Example in doctest about the DocTestCase class
(quoted from the library ref) :

"""
Under the covers, DocTestSuite() creates a unittest.TestSu ite out of
doctest.DocTest Case instances, and DocTestCase is a subclass of
unittest.TestCa se. DocTestCase isn't documented here (it's an internal
detail), but studying its code can answer questions about the exact
details of unittest integration.
"""

Could you be more specific about the modules/packages
that lack proper examples/documentation ?
When my coworker came to me with
this complaint, my response was "oh, just load the interpreter,
import the module and call dir() on it. Then instantiate some objects and call dir() on them also". My infatuation with Python had kept me from realizing the sheer ridiculousness of that method to learn to
use an API. Needless to say, my coworker's reaction to that statement snapped me out of it. But its the truth. How many of you learn a
module by starting the interpreter
and "playing" around with it and using dir()?


You may also use "help" instead of "dir", or directly
pydoc in a shell:

python>>> help("math")
python>>> help(math) # if 'math' has already been imported
bash$ pydoc math

This kind of documentation system suits me (it is far better
than a raw dir anyway). It supports a 'dotted reference'
description of the path to the objects (ie
package.subpack age.module.hold er.object) that is IMHO very
convenient.

Cheers,

SB

Jul 19 '05 #3
Christopher J. Bottaro wrote:
After we were done, we talked about the pros and cons of the languages.
Funny, the con of Python (documentation) is PHP's strong point. The PHP
manual is extremely easy to navigate and its search feature works great.
Contrast that with Python, where you have to use "the tutorial" as the
manual. Also, the tutorial is just that...a tutorial, its a NOT a manual.
Its not organized like a manual and its not comprehensive like a manual,
hell, raw_input() isn't even mentioned in Chapter 7. Input and Output.
[snip]
What do yall think?


I have to say, I don't really have your troubles with the documentation,
and I hardly ever use dir() in the interactive shell. You mention only
referring to the tutorial. Why don't you check the Language
Reference[1] or Library Reference[2]?

That said, if you see spots where the documentation needs help, the
right answer is to file a feature request[3] to add documentation. If
you're feeling especially helpful, providing the documentation you'd
like to be added would be greatly appreciated. Python's a community
effort -- if you see weak points, you can help the community build a
better Python by taking the time to address them yourself.

STeVe

[1]http://docs.python.org/ref/ref.html
[2]http://docs.python.org/lib/lib.html
[3]http://sourceforge.net/tracker/?group_id=5470& atid=355470
Jul 19 '05 #4
hu****@gmail.co m wrote:
I think Python's doc really rock. It's odd, why do you refer to the
tutorial when the lib API is what I'd consider "the docs".


I guess I mean Python needs a manual, which is basically what the tutorial
serves as, but its not comprehensive and organized like how (I think) a
manual should be.

Jul 19 '05 #5
Steven Bethard wrote:
Christopher J. Bottaro wrote:
After we were done, we talked about the pros and cons of the languages.
Funny, the con of Python (documentation) is PHP's strong point. The PHP
manual is extremely easy to navigate and its search feature works great.
Contrast that with Python, where you have to use "the tutorial" as the
manual. Also, the tutorial is just that...a tutorial, its a NOT a
manual. Its not organized like a manual and its not comprehensive like a
manual, hell, raw_input() isn't even mentioned in Chapter 7. Input and
Output.
[snip]

What do yall think?


I have to say, I don't really have your troubles with the documentation,
and I hardly ever use dir() in the interactive shell. You mention only
referring to the tutorial. Why don't you check the Language
Reference[1] or Library Reference[2]?


Cuz I think the Language Reference is really more of a grammer reference and
far too technical to look up simple things like "how to declare a
function".

I guess what I'm trying to say is that there is no manual (for the language
itself, not the modules). There is just the tutorial that serves as the
manual. I think it should evolve into a manual that is more comprehensive
and organized more like other programming manuals (chapter on control
structures, functions, classes, inheritance, etc).

Kinda funny...I was going to use the email module as an example of a module
that lacks examples...but apparently that has been updated since when I
last used it...=)
That said, if you see spots where the documentation needs help, the
right answer is to file a feature request[3] to add documentation. If
you're feeling especially helpful, providing the documentation you'd
like to be added would be greatly appreciated. Python's a community
effort -- if you see weak points, you can help the community build a
better Python by taking the time to address them yourself.
That true, but to be perfectly honest...I don't feel qualified. I'm still a
young'un in this programming game. I'm sure a lot of seasoned devs would
scoff at the documentation I write.
STeVe
-- C
[1]http://docs.python.org/ref/ref.html
[2]http://docs.python.org/lib/lib.html
[3]http://sourceforge.net/tracker/?group_id=5470& atid=355470

Jul 19 '05 #6

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

Right ?

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

Cheers,

SB

Jul 19 '05 #7
Christopher J. Bottaro wrote:
I think it should evolve into a manual that is more comprehensive
and organized more like other programming manuals (chapter on control
structures,
http://docs.python.org/tut/node6.html
or
http://docs.python.org/ref/compound.html
functions,
http://docs.python.org/tut/node6.htm...00000000000000
http://docs.python.org/tut/node6.htm...00000000000000
or
http://docs.python.org/ref/function.html
classes, inheritance, etc


http://docs.python.org/tut/node11.html
or
http://docs.python.org/ref/class.html
Note that the first examples above are from the tutorial, the second
form the language reference.

Personally, I would think that for 99% of users, going through the
tutorial should be sufficient (it was for me). I only use the language
reference when I need to explain a particular detail of why Python does
something.

Was there something that wasn't in the tutorial that you would have
liked to be? The more specific you can get, the more easily we can
improve the documentation.
That said, if you see spots where the documentation needs help, the
right answer is to file a feature request[3] to add documentation. If
you're feeling especially helpful, providing the documentation you'd
like to be added would be greatly appreciated. Python's a community
effort -- if you see weak points, you can help the community build a
better Python by taking the time to address them yourself.


That true, but to be perfectly honest...I don't feel qualified. I'm still a
young'un in this programming game. I'm sure a lot of seasoned devs would
scoff at the documentation I write.


Well then at least file a feature request and indicate what was missing
from the documentation, or what part of it confused you. Even if you
throw in a few phrases of documentation that never get used, at least
they might give the dev who updates the documentation a better idea of
the problem you encountered.

STeVe
Jul 19 '05 #8

Christopher J. Bottaro wrote:
[...] Cuz I think the Language Reference is really more of a grammer reference and far too technical to look up simple things like "how to declare a
function".

I guess what I'm trying to say is that there is no manual (for the language itself, not the modules). There is just the tutorial that serves as the manual. I think it should evolve into a manual that is more comprehensive and organized more like other programming manuals (chapter on control
structures, functions, classes, inheritance, etc).


Fair enough. An 'upgraded' tutorial that would include simple
discussion on some 'advanced topics' could be helpful. For example,
there is (almost) no reference to the new-style classes inside the
tutorial, the "yield" keyword and generator stuff is described in
half a page, etc.

SB

Jul 19 '05 #9
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

Jul 19 '05 #10

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

40
2699
by: =?iso-8859-1?B?QW5kcuk=?= | last post by:
I'm really annoyed at Python - and not for the reasons already mentioned on this list. Everyone know that programming is supposed to be a dark art, nearly impossible to learn. Computer code is supposed to be something impossible to read to the common person and yet reveal their secrets to the initiated - just remember the code displayed in...
0
7811
by: Hystou | last post by:
Most computers default to English, but sometimes we require a different language, especially when relocating. Forgot to request a specific language before your computer shipped? No problem! You can effortlessly switch the default language on Windows 10 without reinstalling. I'll walk you through it. First, let's disable language...
0
8159
Oralloy
by: Oralloy | last post by:
Hello folks, I am unable to find appropriate documentation on the type promotion of bit-fields when using the generalised comparison operator "<=>". The problem is that using the GNU compilers, it seems that the internal comparison operator "<=>" tries to promote arguments from unsigned to signed. This is as boiled down as I can make it. ...
0
8314
jinu1996
by: jinu1996 | last post by:
In today's digital age, having a compelling online presence is paramount for businesses aiming to thrive in a competitive landscape. At the heart of this digital strategy lies an intricately woven tapestry of website design and digital marketing. It's not merely about having a website; it's about crafting an immersive digital experience that...
1
5689
isladogs
by: isladogs | last post by:
The next Access Europe User Group meeting will be on Wednesday 1 May 2024 starting at 18:00 UK time (6PM UTC+1) and finishing by 19:30 (7.30PM). In this session, we are pleased to welcome a new presenter, Adolph Dupré who will be discussing some powerful techniques for using class modules. He will explain when you may want to use classes...
0
3811
by: TSSRALBI | last post by:
Hello I'm a network technician in training and I need your help. I am currently learning how to create and manage the different types of VPNs and I have a question about LAN-to-LAN VPNs. The last exercise I practiced was to create a LAN-to-LAN VPN between two Pfsense firewalls, by using IPSEC protocols. I succeeded, with both firewalls in...
0
3836
by: adsilva | last post by:
A Windows Forms form does not have the event Unload, like VB6. What one acts like?
1
2317
by: 6302768590 | last post by:
Hai team i want code for transfer the data from one system to another through IP address by using C# our system has to for every 5mins then we have to update the data what the data is updated we have to send another system
1
1416
muto222
by: muto222 | last post by:
How can i add a mobile payment intergratation into php mysql website.
0
1147
bsmnconsultancy
by: bsmnconsultancy | last post by:
In today's digital era, a well-designed website is crucial for businesses looking to succeed. Whether you're a small business owner or a large corporation in Toronto, having a strong online presence can significantly impact your brand's success. BSMN Consultancy, a leader in Website Development in Toronto offers valuable insights into creating...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.