I'm pretty new to Python, and I like a lot overall, but I find the documentation for Python rather poor, overall.
I'm sure that Python experts don't have this problem: they have internalized some good ways to access the documentation, are productive with it, and therefore have lost the ability to see why the Python documentations is deficient for beginners. This explains why a suboptimal situation can persist like this: those who are most able fix it are also the least able to perceive it.
I've heard similar complaints from other experienced programmers who are trying out Python for the first time: poor documentation.
Here is an *entirely typical* example: on some Unix, try
% pydoc urllib
The displayed documentation mention the optional parameter "data" in practically every function listed (a few dozen of them). This parameter is not documented *anywhere* on that page. All that we are told is that its default value is always None.
I'm sure that I can find a full description of this parameter if I fire up Google, and search online. In fact, more likely than not, I'll find far more documentation than I want. But my point is that a programmer should not need to do this. The full documentation should be readily accessible directly through a few keystrokes.
I would love to know how experienced Python programmers quickly zero in on the Python documentation they need.
I use Firefox's "Quick Searches" feature to make getting this URL as fast as possible:
"m urllib"
-- Robert Kern
"I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
On Jul 31, 3:10 pm, kj <no.em...@please.post> wrote:
> I'm pretty new to Python, and I like a lot overall, but I find the > documentation for Python rather poor, overall.
[snip]
If you mean the built-in docs i *highly agree* with you. if you mean docs/tutorials available across the WWW i *highly disagree* with you, and if you mean the command line "help" i also *highly disagree*, of which python has the-best-in the-world!
I am using 2.6.2 and the help docs are a joke. trying to find even the simplest thing (built-in functions, etc...) is like pulling teeth. I do not look at them anymore, or do i plan to in the future. Luckily i know python pretty well, but i can't image the horrors a new Python Programmer must face now...
Kj, you could not be more right. Doc maintainers need to get some feedback from Python noobies when writing this stuff. Does anybody remember CP4E? I know Guido put a lot of effort into this project and very much believed in this philosophy(circa 1999~2005), although it never really went very far, i still believe in Guido's heart the CP4E exists -- if only barley clinging to life(...maybe?)
> I'm pretty new to Python, and I like a lot overall, but I find the > documentation for Python rather poor, overall.
> I'm sure that Python experts don't have this problem: they have > internalized some good ways to access the documentation, are > productive with it, and therefore have lost the ability to see why > the Python documentations is deficient for beginners. This explains > why a suboptimal situation can persist like this: those who are > most able fix it are also the least able to perceive it.
> I've heard similar complaints from other experienced programmers > who are trying out Python for the first time: poor documentation.
The documentation on python.org is quite extensive. In particular, you may want to look at the PEPs, which offer fascinating insights for the reasoning behind particular features of Python.
> Here is an *entirely typical* example: on some Unix, try
> % pydoc urllib
> The displayed documentation mention the optional parameter "data" > in practically every function listed (a few dozen of them). This > parameter is not documented *anywhere* on that page. All that we > are told is that its default value is always None.
> I'm sure that I can find a full description of this parameter if > I fire up Google, and search online. In fact, more likely than > not, I'll find far more documentation than I want. But my point > is that a programmer should not need to do this. The full > documentation should be readily accessible directly through a few > keystrokes.
You have first-grade documentation on the Python website: http://docs.python.org/library/urllib.html I'm not really using pydoc, but I'd wager it's more used as a quick lookup than anything else.
> I would love to know how experienced Python programmers quickly > zero in on the Python documentation they need.
I wouldn't count myself as an 'experienced' Python programmer, but I rely on docs.python.org for most things with regards to the standard library.
r wrote: > On Jul 31, 3:10 pm, kj <no.em...@please.post> wrote: >> I'm pretty new to Python, and I like a lot overall, but I find the >> documentation for Python rather poor, overall. > [snip]
> If you mean the built-in docs i *highly agree* with you. if you mean > docs/tutorials available across the WWW i *highly disagree* with you, > and if you mean the command line "help" i also *highly disagree*, of > which python has the-best-in the-world!
> I am using 2.6.2 and the help docs are a joke. trying to find even the > simplest thing (built-in functions, etc...) is like pulling teeth. I > do not look at them anymore, or do i plan to in the future. Luckily i > know python pretty well, but i can't image the horrors a new Python > Programmer must face now...
> Kj, you could not be more right. Doc maintainers need to get some > feedback from Python noobies when writing this stuff. Does anybody > remember CP4E? I know Guido put a lot of effort into this project and > very much believed in this philosophy(circa 1999~2005), although it > never really went very far, i still believe in Guido's heart the CP4E > exists -- if only barley clinging to life(...maybe?)
> any thoughts on this Pythonistas?
I entirely agree with these comments. Looking at home on the compiled help file on windows for python 2.6.2 I can't see anything except for some icons at the top, the Contents, Index, Search and Favorites tabs on the left and the following on the right.
What's new in Python 2.6? or all "What's new" documents since 2.0 Tutorial start here Using Python how to use Python on different platforms Language Reference describes syntax and language elements Library Reference keep this under your pillow Python HOWTOs in-depth documents on specific topics Extending and Embedding tutorial for C/C++ programmers Python/C API reference for C/C++ programmers Installing Python Modules information for installers & sys-admins Distributing Python Modules sharing modules with others Documenting Python guide for documentation authors Indices and tables: Global Module Index quick access to all modules General Index all functions, classes, terms Glossary the most important terms explained Search page search this documentation Complete Table of Contents lists all sections and subsections Meta information: Reporting bugs About the documentation History and License of Python Copyright
Apart from that what have the Pythonistas ever done for us? Nothing!:)
On Jul 31, 1:10 pm, kj <no.em...@please.post> wrote:
> I'm pretty new to Python, and I like a lot overall, but I find the > documentation for Python rather poor, overall.
> I'm sure that Python experts don't have this problem: they have > internalized some good ways to access the documentation, are > productive with it, and therefore have lost the ability to see why > the Python documentations is deficient for beginners.
That may be so, but I do remember when I was a beginner myself and I had no issue with the documentation.
[snip]
> I'm sure that I can find a full description of this parameter if > I fire up Google, and search online.
Are you aware that Python ships with a full set of documentation, where (for instance) the meaning of "data" in urllib is defined? You don't need Google.
> In fact, more likely than > not, I'll find far more documentation than I want. But my point > is that a programmer should not need to do this. The full > documentation should be readily accessible directly through a few > keystrokes.
Well, no one volunteered to do that. Oh well.
> I would love to know how experienced Python programmers quickly > zero in on the Python documentation they need.
Choose bookmark in web browser for Python documentation -> keyword search for correct module (easy with firefox) -> scroll.
This might not be the smoothest method ever (omg you have to use a *mouse*) but it should be usable enough.
On 31 Jul 2009, at 22:34 , Emmanuel Surleau wrote:
> You have first-grade documentation on the Python website: > http://docs.python.org/library/urllib.html > I'm not really using pydoc, but I'd wager it's more used as a quick > lookup > than anything else.
Another important documentary resource for the stdlib is Doug Hellmann's awesome Python Module of the Day series (http://www.doughellmann.com/PyMOTW/ )
In <e22013d0-fbad-44e0-919b-ad5bb5f2d...@g19g2000vbi.googlegroups.com> Carl Banks <pavlovevide...@gmail.com> writes:
>(omg you have to use a >*mouse*)
That's precisely the point. There's a huge number of programmers out there who, like me, *hate* to use the mouse while they're coding. It is truly disappointing to us that the developers of Python chose to completely disregard this constituency.
This is one area in which Perl still whips Python...
On Jul 31, 4:16 pm, Carl Banks <pavlovevide...@gmail.com> wrote:
> On Jul 31, 1:10 pm, kj <no.em...@please.post> wrote:
> > I'm pretty new to Python, and I like a lot overall, but I find the > > documentation for Python rather poor, overall.
> > I'm sure that Python experts don't have this problem: they have > > internalized some good ways to access the documentation, are > > productive with it, and therefore have lost the ability to see why > > the Python documentations is deficient for beginners.
> That may be so, but I do remember when I was a beginner myself and I > had no issue with the documentation.
have you tried the new docs (>= 2.6) The interface has changed drastically as to render itself completely useless. The old docs (<= 2.5) --the ones i learned from-- where flawless.
@ Mark Lawrence Have you clicked any of those links? try the "Tutorial start here" and then try to find a menu of sorts. It seems you have to click "next" to navigate. Thats pretty counter intuitive if you need to get to page 589!! Upon clicking the tutorial link in the OLD DOCS, you where presented with a nice menu for concise navigation.
r wrote: > On Jul 31, 4:16 pm, Carl Banks <pavlovevide...@gmail.com> wrote: >> On Jul 31, 1:10 pm, kj <no.em...@please.post> wrote:
>>> I'm pretty new to Python, and I like a lot overall, but I find the >>> documentation for Python rather poor, overall. >>> I'm sure that Python experts don't have this problem: they have >>> internalized some good ways to access the documentation, are >>> productive with it, and therefore have lost the ability to see why >>> the Python documentations is deficient for beginners. >> That may be so, but I do remember when I was a beginner myself and I >> had no issue with the documentation.
> have you tried the new docs (>= 2.6) The interface has changed > drastically as to render itself completely useless. The old docs (<= > 2.5) --the ones i learned from-- where flawless.
> @ Mark Lawrence > Have you clicked any of those links? try the "Tutorial start here" and > then try to find a menu of sorts. It seems you have to click "next" to > navigate. Thats pretty counter intuitive if you need to get to page > 589!! Upon clicking the tutorial link in the OLD DOCS, you where > presented with a nice menu for concise navigation.
Yes. Works perfectly as evidenced by the fact that this evening I've checked data on the cProfile, pstats and array modules.
On Jul 31, 2:28 pm, kj <no.em...@please.post> wrote:
> In <e22013d0-fbad-44e0-919b-ad5bb5f2d...@g19g2000vbi.googlegroups.com> Carl Banks <pavlovevide...@gmail.com> writes:
> >(omg you have to use a > >*mouse*)
> That's precisely the point. There's a huge number of programmers > out there who, like me, *hate* to use the mouse while they're > coding.
You would have figured one of them would have written a script or something if there were so many. Maybe check the Python Cookbook for someone's pet trick, I bet there is one or two there. Or figure out a way to use elinks, the text mode web browser. You know, text mode browsers have come a long way since the lynx days.
> It is truly disappointing to us that the developers of > Python chose to completely disregard this constituency.
Python is a volunteer effort, chief.
If all these programmers have this itch, as you claim, they've all disregarded themselves by failing to contribute something.
> This is one area in which Perl still whips Python...
No way. Perl's man pages are organized so poorly there is no ergonomic pit deep enough to offset them. Quick, what man page is the "do" statement documented in?
Thanks. Your remarks at least confirm that my impression was not simply due to my noob ignorance: the keyboard-accessible docs are indeed as poor as they look.
Carl Banks <pavlovevide...@gmail.com> writes: >> This is one area in which Perl still whips Python...
> No way. Perl's man pages are organized so poorly there is no > ergonomic pit deep enough to offset them. Quick, what man page is the > "do" statement documented in?
Of course there is:
$ perldoc -f do | head do BLOCK Not really a function. Returns the value of the last command in the sequence of commands indicated by BLOCK. When modified by the "while" or "until" loop modifier, executes the BLOCK once before testing the loop condition. (On other statements the loop modifiers test the conditional first.)
"do BLOCK" does not count as a loop, so the loop control statements "next", "last", or "redo" cannot be used to leave or restart the block. See perlsyn for alternative strategies. $
Best,
-Nikolaus
-- »Time flies like an arrow, fruit flies like a Banana.«
> Thanks. Your remarks at least confirm that my impression was not > simply due to my noob ignorance: the keyboard-accessible docs are > indeed as poor as they look.
In the standard library, docstrings (which is what pydoc prints) are intended to be a brief explanation/reminder of usage, not an exhaustive description. Where docstrings are present, they are more or less adequate for their intended use (although the quality of docstrings does vary highly throughout the library).
If you are trying to use pydoc in a way not intended, then yes you would likely find that they are poor when used in that unintended way.
Docstrings take up memory in a running process, so they are not ever likely to be converted to an exhaustive description. Your best bet is to figure out a way to automate lookup in the html documentation.
On Fri, Jul 31, 2009 at 06:03:25PM EDT, Carl Banks wrote: > On Jul 31, 2:28 pm, kj <no.em...@please.post> wrote: > > In <e22013d0-fbad-44e0-919b-ad5bb5f2d...@g19g2000vbi.googlegroups.com> Carl Banks <pavlovevide...@gmail.com> writes:
> > >(omg you have to use a > > >*mouse*)
> > That's precisely the point. There's a huge number of programmers > > out there who, like me, *hate* to use the mouse while they're > > coding.
> You would have figured one of them would have written a script or > something if there were so many. Maybe check the Python Cookbook for > someone's pet trick, I bet there is one or two there. Or figure out a > way to use elinks, the text mode web browser. You know, text mode > browsers have come a long way since the lynx days.
So true.. I would add that one of the unplanned merits of a well-thought out text mode browser such as ELinks is to remove all the fluff and leave you, the reader, face to face with the site's content - or lack thereof.
> r wrote: > > On Jul 31, 4:16 pm, Carl Banks <pavlovevide...@gmail.com> wrote: > >> On Jul 31, 1:10 pm, kj <no.em...@please.post> wrote:
> >>> I'm pretty new to Python, and I like a lot overall, but I find the > >>> documentation for Python rather poor, overall. > >>> I'm sure that Python experts don't have this problem: they have > >>> internalized some good ways to access the documentation, are > >>> productive with it, and therefore have lost the ability to see why > >>> the Python documentations is deficient for beginners. > >> That may be so, but I do remember when I was a beginner myself and I > >> had no issue with the documentation.
> > have you tried the new docs (>= 2.6) The interface has changed > > drastically as to render itself completely useless. The old docs (<= > > 2.5) --the ones i learned from-- where flawless.
> > @ Mark Lawrence > > Have you clicked any of those links? try the "Tutorial start here" and > > then try to find a menu of sorts. It seems you have to click "next" to > > navigate. Thats pretty counter intuitive if you need to get to page > > 589!! Upon clicking the tutorial link in the OLD DOCS, you where > > presented with a nice menu for concise navigation.
> Yes. Works perfectly as evidenced by the fact that this evening I've > checked data on the cProfile, pstats and array modules.
> -- > Kindest regards.
> Mark Lawrence.
Hold the phone... You checked data on modules using the "Tutorial Start Here" link? Would not the "Global Module Index" be more, shall we say, "informative"?
I too find the Python docs not very useful and it really slows down my learning curve.
I wonder if it would make sense to find good tech writers, get a quotes, and get some professionally written documentation WITH LOTS OF EXAMPLES added to the standard Python documentation tree.
I'd chip in money for that task. I've certainly spent enough buying Python books to where it would be very reasonable to chip in the cost of one book towards this project. Get enough people ... could be a great thing.
Even though it is not the version I use, I would suggest that the really detailed docs with lots of examples be written against the latest python version.
If you are totally new to programming _and_ you won't/can't invest in educational material _and_ have an adversity for looking up resources using a web browser _and_ don't have the patience for trial and error *then* getting proficient with the language is almost impossible.
Sometimes some modules are completely incomprehensible for me and that is after I have looked at the docstrings, the python doc and examples found using Google. However usually after combining all three with a fair bit of experimenting I figure it out, to me that is fun I like that kind of puzzles but I am aware that this isn't the best possible situation.
Overall I would say a better situation would be if the standard python documentation would have an *extensive* 'pattern' section for each module much like, for example, Frederik Lundh did this with his tkinter documentation. Incorporating these patterns in the standard documentation would save you some jumping around sites and it is perhaps more 'trustworthy' coming from the source (pun intended).
I believe that the documentation is all ReST format, so there should be a way (if there isn't already) to display the extensive documentation from the interpreter directly for the module you are working with. As you probably noticed, I actually never bothered to look if this isn't already the case. Which is a good indication to how much it has actually bothered me.
Furthermore I like to add to my reply, which is already longer then I anticipated at first, the thing I don't agree with you is the following (and comparative in nature): Compared to all other 'popular' languages I find Python actually very, very good documented and if you can't learn Python using the available documentation and on-line resources I think it is unlikely you can learn any other language, whether this is a programming language or a natural language. Actually, I should have replaced 'any' with 'anything' followed by a full stop.
-- MPH http://blog.dcuktec.com 'If consumed, best digested with added seasoning to own preference.'
r wrote: > On Jul 31, 4:53 pm, Mark Lawrence <breamore...@yahoo.co.uk> wrote: >> r wrote: >>> On Jul 31, 4:16 pm, Carl Banks <pavlovevide...@gmail.com> wrote: >>>> On Jul 31, 1:10 pm, kj <no.em...@please.post> wrote: >>>>> I'm pretty new to Python, and I like a lot overall, but I find the >>>>> documentation for Python rather poor, overall. >>>>> I'm sure that Python experts don't have this problem: they have >>>>> internalized some good ways to access the documentation, are >>>>> productive with it, and therefore have lost the ability to see why >>>>> the Python documentations is deficient for beginners. >>>> That may be so, but I do remember when I was a beginner myself and I >>>> had no issue with the documentation. >>> have you tried the new docs (>= 2.6) The interface has changed >>> drastically as to render itself completely useless. The old docs (<= >>> 2.5) --the ones i learned from-- where flawless. >>> @ Mark Lawrence >>> Have you clicked any of those links? try the "Tutorial start here" and >>> then try to find a menu of sorts. It seems you have to click "next" to >>> navigate. Thats pretty counter intuitive if you need to get to page >>> 589!! Upon clicking the tutorial link in the OLD DOCS, you where >>> presented with a nice menu for concise navigation. >> Yes. Works perfectly as evidenced by the fact that this evening I've >> checked data on the cProfile, pstats and array modules.
>> -- >> Kindest regards.
>> Mark Lawrence.
> Hold the phone... You checked data on modules using the "Tutorial > Start Here" link? Would not the "Global Module Index" be more, shall > we say, "informative"?
You asked "Have you clicked any of those links?". I answered yes since they all work. I usually navigate to module data via the index tab as I find this the easiest way. I'm sure other people prefer the global module index. Six of one, half a dozen of the other?
In article <h4vnm4$jv...@reader1.panix.com>, kj <no.em...@please.post> wrote: >In <e22013d0-fbad-44e0-919b-ad5bb5f2d...@g19g2000vbi.googlegroups.com> Carl Banks <pavlovevide...@gmail.com> writes:
>>(omg you have to use a *mouse*)
>That's precisely the point. There's a huge number of programmers out >there who, like me, *hate* to use the mouse while they're coding. It >is truly disappointing to us that the developers of Python chose to >completely disregard this constituency.
That's why I use Lynx on a local copy of the Python docs. Next question? -- Aahz (a...@pythoncraft.com) <*> http://www.pythoncraft.com/
"Many customs in this life persist because they ease friction and promote productivity as a result of universal agreement, and whether they are precisely the optimal choices is much less important." --Henry Spencer
On Fri, 31 Jul 2009 21:28:36 +0000, kj wrote: > In <e22013d0-fbad-44e0-919b-ad5bb5f2d...@g19g2000vbi.googlegroups.com> > Carl Banks <pavlovevide...@gmail.com> writes:
>>(omg you have to use a >>*mouse*)
> That's precisely the point. There's a huge number of programmers out > there who, like me, *hate* to use the mouse while they're coding.
Complain to the developers of your web browser then. Or use a different web browser.
> It is > truly disappointing to us that the developers of Python chose to > completely disregard this constituency.
Python is open source software developed by a community of volunteers, so *you* are one of the developers of Python. You have an itch that needs scratching. Solve it yourself, and release it to the wider community, don't expect somebody else to do so.
Nobody is entitled to any functionality in Python. You can ask for it nicely, and if somebody thinks it's a good idea, and have nothing better to do, they may code it out of the goodness of their heart. Or you can do it yourself, or you can pay somebody to do it if you don't have the technical skill yourself. Or you can do without.
> This is one area in which Perl still whips Python...
If so, it's because Perl has more people who understand that the way to get something done is to do it, rather than whining about it.
>> I'm sure that I can find a full description of this parameter if >> I fire up Google, and search online. In fact, more likely than >> not, I'll find far more documentation than I want. But my point >> is that a programmer should not need to do this. The full >> documentation should be readily accessible directly through a few >> keystrokes.
> Well to a level I agree with you. [snip] > have an adversity for looking up resources using a web browser
It may not be an adversity for looking things up using a web-browser, but rather the need to access documentation offline. Whether on an airplane or simply away from a wifi/landline connection, there are plenty of times I'm coding offline (another reason I'm happy to have DVCS tools).
This thread prompted me to go digging a little further, and all the online docs are available in downloadable format, but you have to start by going to the base docs and chasing down the "downloads" rabbit-hole. Perhaps it would be easier if there were some sort of back-link from individual pages, referencing the downloadable format package.
Combined with the downloaded HTML version of the docs (there are PDFs too if you prefer), using a lightweight browser like lynx/links/dillo, and optionally adding htdig for local search/indexing, you can access (and search) the full docs offline.
Tim Chase wrote: > It may not be an adversity for looking things up using a web-browser, > but rather the need to access documentation offline. Whether on an > airplane or simply away from a wifi/landline connection, there are > plenty of times I'm coding offline (another reason I'm happy to have > DVCS tools).
This is one area where Windows users seems to have an advantage. The standard installer includes the doc set as a Windows help file. I often keep that open in one window while programming in others. I only later discovered that this was a copy of the online docs ;-), which I only use to check the in-development version before submitting a doc bug.
In article <h50c6a$dg...@ger.gmane.org>, Terry Reedy <tjre...@udel.edu> wrote:
> This is one area where Windows users seems to have an advantage. The > standard installer includes the doc set as a Windows help file. I often > keep that open in one window while programming in others. I only later > discovered that this was a copy of the online docs ;-), which I only use > to check the in-development version before submitting a doc bug.
The python.org Mac OS X installers include the complete documentation set for that version in HTML; the IDLE Help menu will open the front page in a browser (from where you can bookmark it for later use).
