Python docs disappointing
kj
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.
TIA!
kynn
Robert Kern
> I would love to know how experienced Python programmers quickly
> zero in on the Python documentation they need.
http://docs.python.org/library/urllib
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
r
> I'm pretty new to Python, and I like a lot overall, but I find the
> documentation for Python rather poor, overall.
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?
Emmanuel Surleau
> 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.
Cheers,
Emm
Mark Lawrence
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!:)
--
Kindest regards.
Mark Lawrence.
Carl Banks
> 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.
Carl Banks
Masklinn
> 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.
Hellmann's awesome Python Module of the Day series (http://www.doughellmann.com/PyMOTW/
)
Carl Banks
> Apart from that what have the Pythonistas ever done for us? Nothing!:)
Please don't feed the trolls.
And if you do feed the trolls don't smile at them.
Carl Banks
kj
>(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...
kynn
r
> 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.
Mark Lawrence
Yes. Works perfectly as evidenced by the fact that this evening I've
checked data on the cProfile, pstats and array modules.
Carl Banks
> 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?
Carl Banks
kj
Carl Banks <pavlove...@gmail.com> writes:
<snip>
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.
kynn
Nikolaus Rath
>> 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.«
PGP fingerprint: 5B93 61F8 4EA2 E279 ABF6 02CF A9AD B7F8 AE4E 425C
Carl Banks
>
> Carl Banks <pavlovevide...@gmail.com> writes:
>
> <snip>
>
> 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.
Carl Banks
Chris Jones
> 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.
CJ
r
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"?
Kee Nethery
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.
Just a thought.
Kee Nethery
Martin P. Hellwig
<cut python has poor documentation explanation>
Well to a level I agree with you.
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.'
Mark Lawrence
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?
Aahz
>In <e22013d0-fbad-44e0...@g19g2000vbi.googlegroups.com> Carl Banks <pavlove...@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 (aa...@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
Steven D'Aprano
> In <e22013d0-fbad-44e0...@g19g2000vbi.googlegroups.com>
> Carl Banks <pavlove...@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.
--
Steven
Tim Chase
> kj wrote:
[excerpt of previously snipped content restored]
>> 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.
>
> 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.
-tkc
Terry Reedy
> 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.
Ned Deily
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).
--
Ned Deily,
n...@acm.org
Nobody
> I'm pretty new to Python, and I like a lot overall, but I find the
> documentation for Python rather poor, overall.
FWIW, I find the module documentation to be mostly adequate.
What's missing is a human-readable language *manual*. The tutorial omits
too much; the language reference may be fine for language lawyering,
but it's not much use otherwise.
jkn
> 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 ActiveState distribution also includes the doc set as a CHM file
(the canonical version didn't used to; one reason why I've used
ActiveState in the past).
I run a dual-boot system and have used a CHM (Windows Compiled help
file format) viewer under Linux to read the Windows help file. This
has been pretty handy in the past.
Unfortunately, the combination of the python 2.6 CHM helpfile style,
and the KChmViewer application gives me body text which is almost
unreadable (black text on dark blue background). I'm not sure if this
a bug in KChmViewer but it's pretty annoying. Anyone else see this?
J^n
Tim Golden
> The ActiveState distribution also includes the doc set as a CHM file
> (the canonical version didn't used to; one reason why I've used
> ActiveState in the past).
It has done for quite some while now: Python 2.3 was the first
and that was released, what, six years ago. Still, you're right;
it used to use plain HTML.
> Unfortunately, the combination of the python 2.6 CHM helpfile style,
> and the KChmViewer application gives me body text which is almost
> unreadable (black text on dark blue background). I'm not sure if this
> a bug in KChmViewer but it's pretty annoying. Anyone else see this?
This was noised about when the new-style docs were first released.
Somehow (I don't run Linux usually) I had the impression it had
been fixed; presumably not. However, rebuilding the docs is not
at all hard: you just need a Python installation and the
HTMLHelp Workshop. Then you can fiddle about with the CSS to
your heart's content.
TJG
jkn
On Aug 1, 8:32 pm, Tim Golden <m...@timgolden.me.uk> wrote:
>
> > Unfortunately, the combination of the python 2.6 CHM helpfile style,
> > and the KChmViewer application gives me body text which is almost
> > unreadable (black text on dark blue background). I'm not sure if this
> > a bug in KChmViewer but it's pretty annoying. Anyone else see this?
>
> This was noised about when the new-style docs were first released.
> Somehow (I don't run Linux usually) I had the impression it had
> been fixed; presumably not. However, rebuilding the docs is not
> at all hard: you just need a Python installation and the
> HTMLHelp Workshop. Then you can fiddle about with the CSS to
> your heart's content.
>
The HTML form of the documents (on python.org) seem fine (dark text on
a light background, with a 'light blue on dark blue' sidebar). I was
guessing that the .CHM was intended to have the same style, and
therefore there was a problem with either my viwer, or with the
conversion. Is this not the case then?
I've just checked using xchm, and this displays OK - but I don't think
it's taking any notice of any styles. FWIW I'm running 4.0-r1; there
is a later release but it's not yet available for my Gentoo
distribution.
Can you point me at any references to this bug in the Python release
world please?
Thanks
J^n
jkn
based Widget' to display HTML content in the application settings of
KchmViewer, all is readable. Hurrah!
I wonder if it is picing up some QT stylesheet I have lying around in
an over-clever way...
J^n
Chris Rebert
>> I'm pretty new to Python, and I like a lot overall, but I find the
>> documentation for Python rather poor, overall.
>>
>> internalized some good ways to access the documentation, are
>> productive with it, and therefore have lost the ability to see why
>> 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.
>>
>> zero in on the Python documentation they need.
> I am a newbie and about a month old with Python. There is a wealth of
> material about Python and I am really enjoying learning Python.
>
> One thing that could have helped Python documentation is that instead of the
> very "raw" doc string, it could have used something like PythonDoc (java doc
> style) so that the functions/classes are documented better. At least I am
> planning to use PythonDoc for the code that I am going to write. Let me know
> if there is a better one..
If you use reStructuredText (http://docutils.sf.net/rst.html), you can
leverage Sphinx (http://sphinx.pocoo.org/), which generates the
superb-looking official Python docs.
Cheers,
Chris
P.S. Please don't top-post (http://en.wikipedia.org/wiki/Top-post) in
the future.
--
http://blog.rebertia.com
Christian Heimes
> I am a newbie and about a month old with Python. There is a wealth of
> material about Python and I am really enjoying learning Python.
>
> One thing that could have helped Python documentation is that instead of the
> very "raw" doc string, it could have used something like PythonDoc (java doc
> style) so that the functions/classes are documented better. At least I am
> planning to use PythonDoc for the code that I am going to write. Let me know
> if there is a better one..
Several projects are trying to improve the doc strings with an extended
syntax. Personally I prefer the epytext syntax from epydoc [1]. It's a
JavaDoc like markup language that extends the raw doc strings with
useful information.
Christian
Ethan Furman
And if you do smile at them, don't show your teeth!
~Ethan~
David Lyon
It isn't totally about the writers...
Peoples egos are also at stake - it seems.
If "Fred X wrote Doc Y".. they don't want their name taken off.. So
they generally speaking don't want the docs changed.
If you talk too much about docs.. you can be told you're OT..
even in a thread about docs...
alex23
> It isn't totally about the writers...
> Peoples egos are also at stake - it seems.
Citation please.
> If "Fred X wrote Doc Y".. they don't want their name taken off.. So
> they generally speaking don't want the docs changed.
Ditto.
> If you talk too much about docs.. you can be told you're OT..
> even in a thread about docs...
And again.
All I've _ever_ seen (on this group at least) is the much repeated
phrase "All patches to the docs are welcomed". If you'd like to cast
aspersions on the characters of those doing the work over actually
contributing yourself, you're certainly free to do so, just don't
expect your claims to be taken seriously.
Other people's refusal to do the work that _you_ consider to be
necessary isn't "ego".
r
> It isn't totally about the writers...
> Peoples egos are also at stake - it seems.
> If "Fred X wrote Doc Y".. they don't want their name taken off.. So
> they generally speaking don't want the docs changed.
> If you talk too much about docs.. you can be told you're OT..
> even in a thread about docs...
This is the most honest post within this thread. Yes i believe --
although it does not make me happy-- that many within this community
are hostile, vulgar, and viscous towards any notion of change if it
comes from outside the "insiders" group (and even sometimes from the
inside). Which is very sad.
Yes sometimes people are just trolling, but this tread has nothing to
do with trolling. kj has a legitimate complaint. Do i believe the docs
are a complete waste of bytes, No! Many people have invested tons of
hard work into them (and i thank them for their hard work). But i do
believe --like all things in this word-- perfection is always just out
of hands reach, we must constantly seek perfection because we can
never attain it. Like any group effort, eventually it will adopt the
idioms of self indulgence. Python dev needs the input of those who are
not experts in the language --especially in the realm of docs.
It is so easy to forget the struggles we face when learning something
new. The accessibility and appeal of Python to new users is in the
best interest of this community. If you don't believe that, you are
pissing on all the years of hard work that has been put in here. You
might as well just tell Guido to "close up shop"
I have posted this once before but i will post it again. Please read
Christopher's words carefully because they apply to this community in
a big way...Don't fall into the trap of narcissism.
Christopher Lasch referring to the pitfalls of Narcissistic societies:
"""In such a society of constant competition, there can be no allies,
and little transparency. The threats to
acquisitions of social symbols are so numerous, varied and frequently
incomprehensible, that defensiveness, as well as competitiveness,
becomes a way of life. Any real sense of community is undermined -- or
even destroyed -- to be replaced by virtual equivalents that strive,
unsuccessfully, to synthesize a sense of community."""
While I agree that some narcissism is vital to an individuals ego in
competitive atmospheres, I do not believe the Python community
warrants this need.
Terry Reedy
> At 08:35 PM 8/5/2009 -0700, r wrote:
>> """... Any real sense of community is undermined -- or
>> even destroyed -- to be replaced by virtual equivalents that strive,
>> unsuccessfully, to synthesize a sense of community."""
>
> good effect.
And what have you done about setting up such a project?
> http://www.php.net/manual/en/language.types.array.php is a prime example
> where 2/3 of the "doc" is user-contributed comments and code.
I consider consider this to an unreadable mishmash. If you and others
want something like that, do it. And quite bitching about the work of
those of us who have done something compact and readable. We are all
volunteers here.
tjr
Kee Nethery
As I struggle through trying to figure out how to make python do
simple stuff for me, I frequently generate samples. If some volunteer
here would point me towards the documentation that would tell me how I
can alter the existing Python docs to include sample code, I'd be more
than happy to do so.
I would like to "do it". Please point me to the docs that tell me how
to "do it" so that we people with newbie questions and a need for
examples can get out of your way and "do it" ourselves.
Thanks,
Kee Nethery
alex23
> As I struggle through trying to figure out how to make python do
> simple stuff for me, I frequently generate samples. If some volunteer
> here would point me towards the documentation that would tell me how I
> can alter the existing Python docs to include sample code, I'd be more
> than happy to do so.
No offence, but the last thing the official documentation needs is
example code written by people learning how to code. Suggest changes,
request clarifications, submit samples for review, sure, but direct
modification by users? I've seen the PHP docs; thanks but no thanks.
> I would like to "do it". Please point me to the docs that tell me how
> to "do it" so that we people with newbie questions and a need for
> examples can get out of your way and "do it" ourselves.
You start by reading this: http://docs.python.org/documenting/index.html
And this: http://www.python.org/dev/contributing/
And this: http://wiki.python.org/moin/WikiGuidelines
The first link, which directly answers your question, is clearly
listed on the doc contents page as "Documenting Python". I'm uncertain
how the docs could be made any _more_ helpful if people aren't
prepared to put effort into reading them. We're a long way away from
direct upload to the brain, unfortunately.
If you're learning the language, you should also consider using more
appropriate resources:
http://mail.python.org/mailman/listinfo/tutor
http://www.doughellmann.com/PyMOTW/
http://diveintopython.org/
The documentation cannot be all things to all people, and it most
certainly can't be a guide to general programming, which is what often
seems to be the issue with novice users. Python's a great language to
learn how to program in, sure, but I would hate to see that become the
focus of the docs.
Sion Arrowsmith
>I consider consider this to an unreadable mishmash.
> something compact and readable.
Are you talking about the language or the documentation? 9-)
(Actually, that might be a serious point: does the approach to
documentation reflect language design?)
--
\S
under construction
Paul Rubin
> No offence, but the last thing the official documentation needs is
> example code written by people learning how to code. Suggest changes,
> request clarifications, submit samples for review, sure, but direct
> modification by users? I've seen the PHP docs; thanks but no thanks.
The PHP docs as I remember are sort of regular (non-publically
editable) doc pages, each of which has a public discussion thread
where people can post questions and answers about the topic of that
doc page. I thought it worked really well. The main thing is that
the good stuff from the comment section gets folded into the actual
doc now and then.
There is something similar with the PostgreSQL docs. There is also
Real World Haskell (http://book.realworld.haskell.org) which has a lot
of interspersed user comments. It would be cool if Python's doc site
did something like it too.
r
...(snip)
> There is something similar with the PostgreSQL docs. There is also
> Real World Haskell (http://book.realworld.haskell.org) which has a lot
> of interspersed user comments. It would be cool if Python's doc site
> did something like it too.
hear! hear!
Wesley Chun
> 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:
kj,
welcome to Python! i'm sorry that you find the documentation lacking.
the one thing about the docs is that they're just pointers to get you
started and aren't very comprehensive. there are plenty of good online
tutorials out there as well as books. in fact, one of my main
motivations for writing "Core Python Programming" was because when i
learned Python 13 years ago, the online docs were enough to get me
started but did not have enough info to help me become an intermediate
Python programmer. there were only *2*(!) Python books out there, and
they were special-topic oriented, not ones to learn the language from.
it took almost a year and a half to write, but from what i hear from
readers and what has been said in reviews, it's pretty comprehensive,
and is a good book to learn Python from. i only wish that *i* had it
when i was learning!
Most "Python experts" do not have the entire language memorized, so
everyone has to look at the docs from time-to-time, not just
beginners. i'll either hit up http://docs.python.org/library/MODULE.html
or flip open my Nutshell or PER references, and finally, i'll google
if i have to (rare). the Python docs are the language manuals and not
necessarily full reference texts, so you have to just take them for
what they are.
hope this helps!
-- wesley
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
"Core Python Programming", Prentice Hall, (c)2007,2001
"Python Fundamentals", Prentice Hall, (c)2009
http://corepython.com
wesley.j.chun :: wescpy-at-gmail.com
python training and technical consulting
cyberweb.consulting : silicon valley, ca
http://cyberwebconsulting.com
alex23
> editable) doc pages, each of which has a public discussion thread
> where people can post questions and answers about the topic of that
> doc page. I thought it worked really well. The main thing is that
> the good stuff from the comment section gets folded into the actual
> doc now and then.
I'd still like to see this kept out of the official docs as much as
possible, mostly for reasons of brevity & clarity. I think the
official docs should be considered definitive and not require a
hermeneutic evaluation against user comments to ensure they're still
correct...
How about a secondary site that embeds the docs and provides
commenting functionality around it? That's certainly a finitely scoped
project that those with issues about the docs could establish and
contribute to, with the possibility of it gaining official support
later once it gains traction.
Jean-Michel Pichavant
documentation site with examples and I also love the current python
documentation.
JM
r
...(snip)
> How about a secondary site that embeds the docs and provides
> commenting functionality around it? That's certainly a finitely scoped
> project that those with issues about the docs could establish and
> contribute to, with the possibility of it gaining official support
> later once it gains traction.
This is by far the most helpful and honest post i have ever seen by
our friend alex23. I have a new found respect for you sir, thanks
-R
Paul Rubin
> I'd still like to see this kept out of the official docs as much as
> possible, mostly for reasons of brevity & clarity. I think the
> official docs should be considered definitive and not require a
> hermeneutic evaluation against user comments to ensure they're still
> correct...
Such evaluation would only do them good. The official docs are full
of errors and omissions, which is why we have this thread going on
here in the newsgroup.
Dave Angel
useful possibility would be for the "official" pages to each have
specially-marked links that possibly lead to such user comments.
Clearly they'd have to marked carefully, so that naive users don't
confuse the two. But otherwise, it feels like a good idea.
In my case, I usually access the docs via the Windows help file. So
it'd be quite easy for me to recognize that once I've gotten to a
browser page, I'm not in Kansas any more. But that could be also
accomplished by having a very different stylesheet for the user comments
page.
DaveA
alex23
> of errors and omissions, which is why we have this thread going on
> here in the newsgroup.
And there is a process for reporting and correcting such errors and
omissions, which is what I pointed out in my post.
Kee Nethery
tracking system with the suggestion of each section in the official
docs linking to a fixed wiki page that can contain user contributions.
The ticket has been closed because this addition to the official docs
is already in the works.
So ... to everyone who thinks there needs to be a place for user
comments to augment the official docs, it's supposed to happen. Same
with corrections to the docs, there is supposed to be a place per
section where people can post corrections to the docs.
I'm looking forward to the acceleration of improvements to the
official docs based upon easy to provide user feedback. Glad to see
that the bug tracking system is going to not be the primary means for
documentation changes.
Kee
r
...(snip)
> I'm looking forward to the acceleration of improvements to the
> official docs based upon easy to provide user feedback. Glad to see
> that the bug tracking system is going to not be the primary means for
> documentation changes.
+1
alex23
> I'm looking forward to the acceleration of improvements to the
> official docs based upon easy to provide user feedback. Glad to see
> that the bug tracking system is going to not be the primary means for
> documentation changes.
I'm not sure what you see as being fundamentally different between
open access to a bug tracker & open access to a wiki, other than it
being a lot more difficult to have threaded discussion on a wiki.
Why exactly is posting an open comment on a bug tracker somehow
inferior to posting an open comment on a wiki?
David Robinow
> Why exactly is posting an open comment on a bug tracker somehow
> inferior to posting an open comment on a wiki?
jealous of outsiders and actively prevents improvements to the docs,
any change, even if only in perception, helps to weaken the hold of
the evil forces holding back the success of Python.
alex23
> When one believes that development is controlled by a cabal which is
> jealous of outsiders and actively prevents improvements to the docs,
> any change, even if only in perception, helps to weaken the hold of
> the evil forces holding back the success of Python.
Yeah, it's clearly all ego and assholes that's preventing Python from
being the enochian equivalent of programming languages :)
Kee Nethery
It's a good question and deserves a good answer.
* Fewer Steps
* Immediate
* Does not need to be formally reviewed
* Easier to search
For all these comments, assume the starting point is the section in a
web page that documents a specific python function. Assume the user is
using the documentation for the first time in attempt to convert to
Python. Thus, this is the only official Python page they have ever
seen, they found it via Google and went directly to it. For example
purposes, I'll use the following page:
http://docs.python.org/reference/lexical_analysis.html
Lets say the user is in section 2.1.3 Comments
Here's the scenario: The user wanted to include "#" in one of their
strings and the IDE kept interpreting it as a comment. But they really
need to use that character in the string. Eventually they find out
that they can escape the character in their string so that Python
stops thinking it is the beginning of a comment. They want other users
to not suffer through the same thing, and they want to contribute to
the betterment of Python, so they want this information saved so that
others can avoid the mistake they were making.
* Fewer Steps:
With the bug tracking system, their only option is to lobby to get the
documentation changed. Lets assume that Python experts all agree that
the docs should get updated with this gotcha (which as a newbie, they
are not sure that is a valid assumption and would probably just halt
in their quest to get the docs updated). But assuming everyone agrees
this is a valuable addition to the docs so that others can avoid the
same error, where on this page dues the user submit this bug? There is
no link on this page to the bug tracking system.
Lets assume they find the bug tracking system through determined
efforts because they believe there has to be such a thing and they are
absolutely sure the powers that be want their input. When they find
the bug tracking system ... they have to create a user account. Then
they have to wait for the confirming email. Finally they get access to
the bug tracking system and being a good citizen, they want to make
sure that they are not duplicating a previously entered bug. What do
they search on? Do they search for 2.1.3? Do they search for "#"?
Chances are, even if they do a whole set of searches, and if there
really is already another bug entered for the exact same issue, they
are unlikely to find it.
So they create a bug and now they need to go back and reference the
link (find the page from their browser history) and type up why they
think their modification to the documentation is worthy. Then once the
bug is submitted ... you get the picture, there are a gazillion steps
just to submit a bug. Most people do not bother to submit little
helpful hints to the docs because it is too much of a pain to do so
and there is zero confidence that as a newbie, anyone cares about what
they found confusing, after all, they are just a newbie and not worthy
of altering the documentation. (Certainly that opinion has been
expressed several times on this mailing list).
With a wiki article tied to each section in the docs, they click on
the link and are taken directly to the wiki page of user contributions
for this specific 2.1.3 section of the docs. They scan the user
comments and see that no one else entered a note about this gotcha.
They click on the edit button, enter their gotcha, save, and they are
done.
* Immediate:
With the bug tracking system, they struggle to find a place to
contribute and then once they make their contribution, they have no
idea whether anyone will ever see it and whether they have just wasted
a bunch of time.
With the wiki link for that section, in less than a minute, they can
see the comments they have left attached to that specific section so
that others can see them too and perhaps avoid the same mistake they
made. A wiki link encourages new users to be contributors. New users
are the absolute best source of what is confusing to a new user.
* Does not need to be formally reviewed:
With the bug tracking system, each bug has to be reviewed by a
volunteer, analyzed, commented on, dealt with.
With a wiki, no one has to look at user comments. They can just leave
them there and ignore them. Other users can police the content and add
additional comments or examples. All the while none of the official
volunteers have to get in the loop. If some official volunteer wants
to improve the docs, they can scan the wiki contributions and use that
as the source for official changes to the docs.
* Easier to search:
Very few people would think to search the bug tracking system for help
with some specific function. If someone is having trouble with the #
sign in their strings, the bug tracking system is not going to be at
the top of their list for search locations, especially when the bug
tracking system is not mentioned and when found requires a confirmed
login.
With a wiki link, the first thing someone will do is click on that to
see if anyone else left notes about the specific problem. If there was
no answer there, they'd search Google and try bunches of different
wordings looking for some clue as to what is happening. I doubt most
users (except for expert users) would ever search the bug tracking
system for hints on why their code is not doing what they expect.
My 2 cents,
Kee
r
(snip)
Kee,
that was an eloquent and enlighting post and i think it speaks volumes
to the lack of inclusion of all Pythoneers in this community. Not to
mention the viscous attitudes and self indulgence we have around here.
For those of you with ADD, Kee was speaking to the hurdles one must
overcome to change even the most minor things within this community.
Change around here almost parallels an act-of-congress with it's de-
motivating burdens that beset a new python user who may wish to add
his or her 2 pennies to the Python wishing well. And i believe like
Kee, most of them just give up and say
"""Oh Well, F### it!"""
Not to mention the never ending droves of naysayers, bullies, smart-
arses, and egomaniacs with their minions and sock-puppets ready at
moments notice to pounce on (and utterly destroy) any feeble noob who
dares to try and enhance the user experience in Python for all of us.
Steven D'Aprano
> > Why exactly is posting an open comment on a bug tracker somehow
> > inferior to posting an open comment on a wiki?
>
> It's a good question and deserves a good answer.
>
> * Fewer Steps
> * Immediate
> * Does not need to be formally reviewed
> * Easier to search
The last one is actually wrong, because the Python bug tracker is indexed
by Google.
As for the rest, you're right that the current bug-tracker puts up
barriers to people submitting comments and bugs. That's actually a good
thing. The only thing worse than not enough information is too much
information, and the current situation does a good job of discouraging
the sorts of people who submit bad bug reports (e.g. duplicates of bug
reports, bug reports for things fixed years ago, bug reports that are due
to mistakes in their code, etc.).
> For example
> purposes, I'll use the following page:
> http://docs.python.org/reference/lexical_analysis.html
> Lets say the user is in section 2.1.3 Comments
Disclaimer: python.org is down at the moment, so I can't check that page
to see precisely what you're talking about.
> Here's the scenario: The user wanted to include "#" in one of their
> strings and the IDE kept interpreting it as a comment. But they really
> need to use that character in the string. Eventually they find out that
> they can escape the character in their string so that Python stops
> thinking it is the beginning of a comment.
Er, that would be a bug in the IDE, surely? Inside strings, # is an
ordinary character with no special meaning.
>>> s = "this is a string with an unescaped # in it"
>>> s
'this is a string with an unescaped # in it'
The Python docs are supposed to be about Python the language, not work-
arounds for IDE bugs.
[...]
> Lets assume that Python experts all agree that
> the docs should get updated with this gotcha (which as a newbie, they
> are not sure that is a valid assumption and would probably just halt
> in their quest to get the docs updated).
Good.
As a newbie, you SHOULD assume that anything you think is a bug is
probably a bug in YOUR code, not Python, and the same goes for
documentation bugs. If you don't understand something in the docs,
chances are that it's a problem with you, not the docs. Your first port
of call should be the tutor list, or here, and not to "fix" the docs by
putting in noise that just gets in the way of the intended audience,
namely experienced developers.
> and there is zero confidence that as a newbie, anyone cares about what
> they found confusing, after all, they are just a newbie and not worthy
> of altering the documentation. (Certainly that opinion has been
> expressed several times on this mailing list).
No, we care. We just don't want to have the docs filled with all the hand-
holding and introductory stuff which the newbie needs. As a developer,
you will outgrow the need for training wheels. Why force training wheels
on the docs that you will be referring to for your entire career as a
programmer, when you only need them for the first few months? There are
plenty of docs aimed at newbies, and mailing lists where you can ask
questions.
Putting user-comments on a separate page separates the noisy, low-value
comments from the good stuff, but it increases the efforts needed by the
webpage admin (who is going to deal with the comment spam? who is going
to go through the user-comments stripping out the total nonsense put in
by helpful ignoramuses?). It works for Wikipedia, because there are tens
of thousands of users contributing small amounts of effort, and hundreds
putting in a lot of effort, but even there there is a major problem with
vandalism. We don't have those resources.
By the way, if a person wants to contribute, and can demonstrate
competence, reliability, good-sense and trustworthiness, there's no
reason why he or she couldn't get a check-in account for the Python docs.
(All the Python docs are written by volunteers.) A good way to
demonstrate these things is by submitting good-quality doc improvements
to the bug-tracker. If a person can't be bothered to do so, because it
requires effort to get an account, that goes a long way to demonstrating
the *lack* of reliability which will disqualify them from the job.
> Very few people would think to search the bug tracking system for help
> with some specific function. If someone is having trouble with the #
> sign in their strings, the bug tracking system is not going to be at
> the top of their list for search locations, especially when the bug
> tracking system is not mentioned and when found requires a confirmed
> login.
You don't need a login to view bug reports, only to modify them.
If you want an open-access documentation system go right ahead and build
one. There are plenty of wikis available to use, and the Python docs are
freely available as your starting point. I might even contribute myself.
I just don't want it mixed in with the official docs: I want a clear
separation between what's officially sanctioned and what's not.
--
Steven
Carl Banks
cybersource.com.au> wrote:
> If you want an open-access documentation system go right ahead and build
> one. There are plenty of wikis available to use, and the Python docs are
> freely available as your starting point. I might even contribute myself.
> I just don't want it mixed in with the official docs: I want a clear
> separation between what's officially sanctioned and what's not.
The PyGame documentation has a "Click to view comments" box. That
would be A. low profile, and B. distinct from official documentation
enough for me.
It'd probably be useful, but might also attract spam and lots of
useless fluff, because it's likely to be much higher volume than
documentation on other projects.
Carl Banks
Paul Rubin
> As for the rest, you're right that the current bug-tracker puts up
> barriers to people submitting comments and bugs. That's actually a good
> thing. The only thing worse than not enough information is too much
> information, and the current situation does a good job of discouraging
> the sorts of people who submit bad bug reports (e.g. duplicates of bug
> reports, bug reports for things fixed years ago, bug reports that are due
> to mistakes in their code, etc.).
Stephen, Alex, etc.: have you actually used the php.net doc system?
Don't knock it til you've tried it. IMO it is superior to Python's
system. I don't use PHP much these days.
Roel Schroeven
I have to use PHP from time to time, in which cases I often have to use
the manual on php.net. I don't like it at all.
The official documentation is often incomplete, leaving out the details
I need and forcing me to read the comments.
Which I don't want to do, since many comments show a lack of
understanding of the subject matter. I have to read all of them, trying
to find out which ones are correct and which ones are wrong (or
misleading) to get the complete picture.
I like Python's documentation, where I can be confident that the
documentation is correct (except in the case of the very exceptional
bug) and mostly clear, much better.
--
The saddest aspect of life right now is that science gathers knowledge
faster than society gathers wisdom.
-- Isaac Asimov
Roel Schroeven
koranthala
The best example that I have seen is djangobook.
The comment system in it is quite exquisite.
It would be good for the Python docs to have such a mechanism.
Kee Nethery
this list towards people who are trying to learn Python feels like it
has become anti-newbies.
Learning a new language is difficult enough without seeing other
newbies getting shamed for not knowing everything there is to know
about Python before asking their questions.
For example, the guy who was looking for Python sample code for the
Google Map API, calling him a troll was harsh. Suggesting he broach
the question to Google was a reasonable answer. By the same token, his
asking this list about the missing Python examples seems reasonable
also. Seems to me that people on a Python list might have some
background knowledge or even samples of the Google Python code that
was no longer on the Google web site.
There seems to be a general consensus among the newbies that other
languages have a user contributions resource tied to the main official
docs to allow newbies to teach each other what they have learned. The
desire is for python.org to have the same kind of support resource so
that us newbies can self support each other.
Kee Nethery
Mark Lawrence
> As someone trying to learn the language I want to say that the tone on
> this list towards people who are trying to learn Python feels like it
> has become anti-newbies.
>
>
> Kee Nethery
My gut feeling (which could of course be wrong) is that many hard core
Pythonistas are cheesed off with newbies who refuse to help themselves.
No evidence that that they've tried any Python tutorial. No evidence
that that they've searched anywhere in an attempt to resolve the problem
before posting. "This code doesn't work, please fix it". Response
often "Please post your actual code, or a snippet that gives the same
exception, and give the complete exception details".
Show that you have made an attempt to help yourself, and the response
here is almost certainly 100% helpful.
Further, I have seen many requests here which are nothing really to do
with Python, say a query about which algorithm to use. Response "Not
really a Python question, but try ...". Put the same question on (say)
the C ng and you'd be told in no uncertain terms to Foxtrot Oscar.
--
Kindest regards.
Mark Lawrence.
Carl Banks
> As someone trying to learn the language I want to say that the tone on
> this list towards people who are trying to learn Python feels like it
> has become anti-newbies.
I don't think this NG is anti-newbie so much as anti-whining-loser.
Unfortunately, some newbies might see this and perceive it to be abuse
of newbies in general. It is not so. People who have chips on their
shoulder, who make loaded, emotionally-provocative comments, who make
no effort on their own, who expect us to do their homework and/or job
for them, etc., there are the people who going to get an unfavorable
tone.
Newbies who ask respectable questions without having an attitude will
generally get respectable answers.
> For example, the guy who was looking for Python sample code for the
> Google Map API, calling him a troll was harsh.
No it wasn't, that guy is Xah Lee, a person who's been trolling Usenet
for a long time. He is best ignored, but I don't blame someone for
snapping at him.
Carl Banks
alex23
> Don't knock it til you've tried it. IMO it is superior to Python's
> system.
I've tried it, a lot. Is it okay for me to keep criticising it now, or
would you like some time to find some other allusion to ignorance with
which to wave away my opinion?
Steven D'Aprano
> Further, I have seen many requests here which are nothing really to do
> with Python, say a query about which algorithm to use. Response "Not
> really a Python question, but try ...". Put the same question on (say)
> the C ng and you'd be told in no uncertain terms to Foxtrot Oscar.
We're a lot friendlier than the C newsgroup.
Personally, I think knowing the right algorithm to use is as much a part
of Python programming as knowing whether to call mystring.upper() or
string.upper(mystring).
--
Steven
Xah Lee
there are frequent posts about python doc's poor quality, and some
efforts to improve the doc (such as wiki or seggestions), about few
times a year (in so much as i've seen), the typical response is
pissing fight, with python priests to tell them not to start another
wiki, or “you should apply in our church first and formulate a PEP
proposal first or kindly donate or otherwise fuckoff”, and so on.
i've wrote several articles about this issue, total time spend on this
is probably more than 2 months full-time work. See:
• Python Documentation Problems
http://xahlee.org/perl-python/python_doc_index.html
just about each article above generates a thread of flames.
I also have re-wrote the entire python regex doc in 2005:
• Pyhton Regex Documentation: String Pattern Matching
http://xahlee.org/perl-python/python_re-write/lib/module-re.html
there are some positive reviews, but most are drawn out by nay-sayers.
I often receive thank you emails for 2 particular articles, which are
most frequently google searched as indicated by my weblog:
• Python Doc Problem Example: gzip
http://xahlee.org/perl-python/python_doc_gzip.html
• Python Doc Problem Example: sort()
http://xahlee.org/perl-python/python_doc_sort.html
• Sorting in Python and Perl
http://xahlee.org/perl-python/sort_list.html
See also:
• Language, Purity, Cult, and Deception
http://xahlee.org/UnixResource_dir/writ/lang_purity_cult_deception.html
Xah
∑ http://xahlee.org/
☄
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. 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.
>
> TIA!
>
> kynn
David Lyon
Since you're talking about documentation, which is a part of python,
don't you think you should be discussing it on python-dev ?
That's where discussions about the documentation should be held.
haha - I'm just curious to see how long it will for them to
shut the discussion down.
Before you do that, you should clearly work out in your own mind
how you think things need to improve. It's not good enough just
saying this or that is bad without having specific ideas on what
needs to change.
Good luck fellow sinner and blasphemer...
How dare you suggest that things could be improved...
ru...@yahoo.com
...
> Before you do that, you should clearly work out in your own mind
> how you think things need to improve. It's not good enough just
> saying this or that is bad without having specific ideas on what
> needs to change.
He did. Did you read, for example, the critique of the gzip
docs for which he gave the url
http://xahlee.org/perl-python/python_doc_gzip.html
There were some things I might not completely agree with
there, but basically, I thought it was right on, including
his suggestions on how to improve it.
r
> Since you're talking about documentation, which is a part of python,
> don't you think you should be discussing it on python-dev ?
Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better
idea, lets go to the IRS and see if we can persuade them to stop
taxing us...
> That's where discussions about the documentation should be held.
> haha - I'm just curious to see how long it will for them to
> shut the discussion down.
Yea, probably not long at all, of course not before the troll calling,
bulling, defamation of character, etc, has lost it's fun.
> Before you do that, you should clearly work out in your own mind
> how you think things need to improve. It's not good enough just
> saying this or that is bad without having specific ideas on what
> needs to change.
see links that xah posted, and there is more he did not post.
> Good luck fellow sinner and blasphemer...
> How dare you suggest that things could be improved...
how dare YOU suggest they NOT be improved!!!
Ethan Furman
> As someone trying to learn the language I want to say that the tone on
> this list towards people who are trying to learn Python feels like it
> has become anti-newbies.
>
> newbies getting shamed for not knowing everything there is to know
> about Python before asking their questions.
>
> question to Google was a reasonable answer. By the same token, his
> asking this list about the missing Python examples seems reasonable
> also. Seems to me that people on a Python list might have some
> background knowledge or even samples of the Google Python code that was
> no longer on the Google web site.
>
> There seems to be a general consensus among the newbies that other
> languages have a user contributions resource tied to the main official
> docs to allow newbies to teach each other what they have learned. The
> desire is for python.org to have the same kind of support resource so
> that us newbies can self support each other.
>
> Kee Nethery
As someone who is (hopefully!) leaving newbieness I can say I have had
no problem with the helpfullness of this list. I will also say that
before I ever posted any questions I had devoured Dive Into Python and
How To Think Like a Computer Scientist Using Python (both excellent),
and I try to put as much detail into my questions as I can so nobody has
to guess what I'm trying to do.
As someone who relies heavily on the docs I will also say that the idea
of giving the ability to modify the official documentation to somebody
who is /learning/ the language is, quite frankly, terrifying. I have no
issues with a seperate system, some of which have been suggested, but
good reference documentation is crucial. If you find examples lacking,
there are plenty of web-sites, or even (dare I say it?) actual hard-copy
books! ;) My bookshelf currently has Learning Python, Programming
Python, Python Cookbook, Python Programming on Win32, and Regular
Expressions. All great books, and not too pricey if you can get them used.
My $0.02.
~Ethan~
r
(snip)
> As someone who relies heavily on the docs I will also say that the idea
> of giving the ability to modify the official documentation to somebody
> who is /learning/ the language is, quite frankly, terrifying.
Ethan,
I think what you and a few others seem to miss is ... Of course nobody
wants Joe-Noob writing the Python docs -- thats lunacy, would you give
your 12 year old the keys to a shiny new corvette? -- No! What people
are asking for is the ability for a noobs input on the official docs,
and for that input to be taken seriously. Sure some of the suggestions
will be nothing more than "helpful ignoramuses" with unhelpful
suggestions as some have said, but the input channels need to be
there. Currently Python dev seems to be more output than input,
however i could be wrong? We some real I/O going on here.
Also the Python tut is full of fluff (sorry Guido) and it contributes
to late learning of the language. Luckily however Python has many
users who really love the language and have taken the time to write
beautiful tutorials that start at various levels of entry. Read xah's
take on the official tutorial, it's spot on baby!
A little note for tutorial writers:
==================================
Dear Expert,
Whilst writing any tutorial on any subject matter please remember, you
may be an expert, but mostly *non-experts* will be reading your
material... pssft, this may come as a surprise, but tutorials are
meant for *NON-EXPERTS*!
Please refrain from stroking your own ego by obstrufcation of the very
ideas you wish to convey to these influential minds. Sure exposing
your huge intelligence to the world may give you warm-fuzzies-in-your-
tummy, but believe me your poor students will be rendered as helpless
as Paris Hilton at a "panties required" spelling bee.
Please try, and i know this is a lot to ask, to use the most simple
explanation to convey the point -- and *only* the point at hand! Take
for example the introduction of functions. You could go with your gut
instinct, "shoot from the hip" and pop off something like this that
prints a Fibonacci series up to n...
def fib(n):
a, b = 0, 1
while b < n:
print b,
a, b = b, a+b
>>> fib(2000)
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
And all you would have accomplished was to blow holes thru the
students mind! Now like the next guy, i love calculating series of
numbers all day, but this is a piss poor example of functions for the
new student, or anybody for that matter! While your student is
racking his brain trying to figure out what "a" and "b" stand for,
much less n, and not to mention what the heck a "Fibonacci" series is
in the first place (Google can help though) , he (the student) has
forgotten that this example is simply how to write and call a
function. A much better example would be the following...
def add(x, y):
print x+y
>>> add(1, 2)
3
WOW, with that small piece of code you have just transported three
main principals of a function in a very simple and strait forward way
smack-dab into the cerebral cortex of the student, and your fingers
did not even break a sweat!
1. function names should describe exactly what they do
2. functions take arguments
3. functions do something with those arguments(like mini programs!)
You could followup with this fine example that extents on the
first...
def add(x, y=2)
return x+y
>>> add(1,2)
>>> print add(1, 2)
3
>>> print add(1)
3
>>> print add(100, 5.5)
100.5
>>> print add()
error...
However Ethan (and Co.), not everybody who downloads Python the first
time knows about this. Also the Python website is filled to the brim
with a hodgepodge of "links-here" "links-there", "links-every-freaking-
where" (are we getting paid by the link people?) causing most noobs
brain to start blowing chunks just while tring to find a good
alternative to the official tut!
Really, it's bloat on a proportion that only elephant sized bloat
wares like M$, M$-Office, Adobe-PDF, and the like, can hold a candle
to. Python really needs and enema, and thats no joke!
David Lyon
wrote:
> As someone who relies heavily on the docs I will also say that the idea
> of giving the ability to modify the official documentation to somebody
> who is /learning/ the language is, quite frankly, terrifying.
What is more terrifying is the way feedback from newbies is handled.
Your statement implies that the only way feedback can be handled is
to throw the keys down in discust and walk away. That's primative
behaviour. And misleading, because that isn't going to happen.
> My bookshelf currently has Learning Python, Programming
> Python, Python Cookbook, Python Programming on Win32, and Regular
> Expressions. All great books, and not too pricey if you can get them
used.
So, what you're advocating is let things stay how they are...
Ignore feedback... tell people to freak off...
Paul Rubin
> Whilst writing any tutorial on any subject matter please remember, you
> may be an expert, but mostly *non-experts* will be reading your
> material... pssft, this may come as a surprise, but tutorials are
> meant for *NON-EXPERTS*!
I think the Python tutorial is aimed at users who are newbies to
Python but not newbies to programming. Writing a tutorial for total
newbies is a completely different problem, that would result in a much
different document that's less useful to the existing tutorial's
intended audience.
Steven D'Aprano
> So, what you're advocating is let things stay how they are...
If it's not broken, don't fix it.
> Ignore feedback... tell people to freak off...
Only useless feedback.
--
Steven
Antoine Pitrou
>
> On Aug 9, 11:02 pm, David Lyon <david.l...@preisshare.net> wrote:
> > Since you're talking about documentation, which is a part of python,
> > don't you think you should be discussing it on python-dev ?
>
> Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better
> idea, lets go to the IRS and see if we can persuade them to stop
> taxing us...
You know, the most interesting thing in this thread is certainly its title :
« Social problems of Python doc »
Yes, the little social problem here should be clear: if you have complaints to
voice or improvements to suggest to the Python docs, you should do so on the
issue tracker (*). For most topics, this is the only reasonable way to signal
problems to the Python developers community, and so it is in most free software
/ open source projects.
Just because you are able to write tongue-in-cheek (**) comments on python-list
or, even worse, on a third party website, and generate a long thread about how
Python doc (supposedly) s*cks
1) doesn't mean there is a legitimate issue (we all know how people can quickly
inflame about empty subjects)
2) even though there can be a legitimate issue, doesn't mean Python developers
will go out of their way and parse the entirety of the messages to find
potentially useful data in them. The bug tracker is the place for this, and it's
your task, if you want to help, to submit suggestions in it.
FYI, the Python doc is very actively maintained nowadays, and bug reports /are/
taken into account. If you think you've got a lot of time for ranting about how
the doc sucks, but don't want to spend the couple of minutes needed to post
issues on the bug tracker, it speaks a lot about your motivation. Admittedly, in
every successful community, there are attention seekers who are not interested
in actual participation.
(**) yes, humour is fine, but it doesn't replace actual, informational content
Antoine.
Mark Lawrence
>>> Since you're talking about documentation, which is a part of python,
>>> don't you think you should be discussing it on python-dev ?
>> Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better
>> idea, lets go to the IRS and see if we can persuade them to stop
>> taxing us...
>
Bruno Desthuilliers
(snip)
>
> A little note for tutorial writers:
> ==================================
>
> Dear Expert,
> Whilst writing any tutorial on any subject matter please remember, you
> may be an expert, but mostly *non-experts* will be reading your
> material...
I can only second Paul on this : just like the K&R, Python's official
tutorial targets experienced programmers, not total noobies.
Ethan Furman
> On Mon, 10 Aug 2009 09:13:34 -0700, Ethan Furman <et...@stoneleaf.us>
> wrote:
>
>>As someone who relies heavily on the docs I will also say that the idea
>>of giving the ability to modify the official documentation to somebody
>>who is /learning/ the language is, quite frankly, terrifying.
>
>
> What is more terrifying is the way feedback from newbies is handled.
>
> Your statement implies that the only way feedback can be handled is
> to throw the keys down in discust and walk away. That's primative
> behaviour. And misleading, because that isn't going to happen.
>
Allow me to put back the sentence you unfairly snipped:
> I have no issues with a seperate system, some of which have been
> suggested, but good reference documentation is crucial. If you find
> examples lacking, there are plenty of web-sites, or even (dare I say
> it?) actual hard-copy books! ;)
To be clear, what I am advocating is that *official documentation not be
opened up to everybody,* _especially not people who don't yet grok the
language_.
>
>>My bookshelf currently has Learning Python, Programming
>>Python, Python Cookbook, Python Programming on Win32, and Regular
>>Expressions. All great books, and not too pricey if you can get them
>
> used.
>
> So, what you're advocating is let things stay how they are...
>
> Ignore feedback... tell people to freak off...
>
>
I had not addressed feedback before, but I shall do so now: Discuss
concern on the Python list first to make sure it is not a lack of
understanding, then, if a legitimate issue with the docs exists, use the
bug tracker. If one can't be bothered to take the time to be a
Responsible Citizen, I am not going to be bothered by lacking that one's
comments/concerns/feed-back.
~Ethan~
ru...@yahoo.com
> r<rt8396<at> gmail.com> writes:
>> On Aug 9, 11:02 pm, David Lyon<david.l...@preisshare.net> wrote:
>>> Since you're talking about documentation, which is a part of python,
>>> don't you think you should be discussing it on python-dev ?
>> Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better
>> idea, lets go to the IRS and see if we can persuade them to stop
>> taxing us...
>
> You know, the most interesting thing in this thread is certainly its title :
> « Social problems of Python doc »
>
> Yes, the little social problem here should be clear: if you have complaints to
> voice or improvements to suggest to the Python docs, you should do so on the
> issue tracker (*). For most topics, this is the only reasonable way to signal
> problems to the Python developers community, and so it is in most free software
> / open source projects.
"the *only* reasonable way"? That's clearly wrong (unless you
want to wiggle in the room provided by "reasonable" or "most").
There is discussion on the dev list, there is discussion here.
The issue tracker is fine for many things, but the process it
provides is equivalent to peep-hole optimization. How does one
submit a tracker issue for something like the overall organization
of the docs (for example, the mis-placement of things like data-
types in the library manual rather than the language manual)?
The big problem with the docs is poor writing (this includes
not using examples when they can help explain something more
clearly than verbiage alone). It is understandable why this
should be so -- most programmers are good at and enjoy
programming, not writing and the python community is, say,
about 99.9% programmers.
This is why all the attempts (at least that I've noticed) are
programming focused -- build a wiki, write a new doc processing
framework, etc. Unfortunately none of those addresses the real
problem -- the need for clear, well written, well organized
*content*. I don't see how telling people to submit tracker
issues will solve this problem. I can rewrite some section so
it sounds good to me, but likely it will be just as bad (perhaps
in different ways) that what is there.
The post that started this thread proposed something like paying
professional writers to improve the docs. This may or may not
be a practical suggestion. But the immediate response it
engendered was an auto-immune-like group response: the docs
are great already, don't complain, fix them yourself, yada, yada;
the same response that any criticism of free software produces.
It's really too bad the the python community can't seriously
discuss ways to improves the docs. There are other possibilities
for instance the Fedora Docs project (can't say I'm impressed
by what they've produced but that doesn't mean their model
is useless). There is a need for an approval process managed
by someone who actually understands what good technical writing
is. And perhaps editors who can polish or work with programmers
who provide the raw technical description of some module.
Some kind of higher level more global process is the only
way I can see that the docs will be improved to any sort
or professional standard. I don't see how issues like this
will be addressed by submitting tracker items.
Personally, I have given up on this issue. The social factors
involved really pretty much determine that the Python docs
will never reach a very high quality -- that's just the way
it is and I've come to accept that.
r
And who decides what is useless and what isn't Steven?. You?, alex23?,
Bruno?, Paul? Carl? Who makes these decisions and do *they* make them
without pride or prejudice? Do they approve an idea by someone they
hate because it it good, or do they toss it in the trash just to spite
them, because they have the power to do so? As we can see much
resistace exists against even the ideas of change. How will change
ever take place with such defiance!
I am sorry but i feel many here would not judge fairly based on the
merits of an idea without allowing "buddy-systems" or "pecking-orders"
to get in the way. Sad really, only Python suffers in the end.
Some say the tutorial is not meant for non-programmers, but for
programmers with no Python experience. So! How does that justify
obstruction of the tut? Why not present the same information in a way
both can easily understand? I thought Pythons original vision was to
allow easy entry into programming for anybody -- experienced or not!
Anybody remember "CP4E"?
Is this an ivory tower thing? i dunno, but it seems to be...???
Mark Lawrence
> On Aug 11, 1:47 am, Steven D'Aprano
> <ste...@REMOVE.THIS.cybersource.com.au> wrote:
>> On Mon, 10 Aug 2009 20:05:00 -0400, David Lyon wrote:
>>> Ignore feedback... tell people to freak off...
>> Only useless feedback.
>
>
> I am sorry but i feel many here would not judge fairly based on the
> merits of an idea without allowing "buddy-systems" or "pecking-orders"
> to get in the way. Sad really, only Python suffers in the end.
buddy system or a pecking order getting in the way of anything. As you
are making thsse accusations, either provide hard evidence that can
persuade me that your perspective on this is correct or shut up.
>
[snip]
Steven D'Aprano
> On 08/11/2009 01:47 AM, Antoine Pitrou wrote:
>> r<rt8396<at> gmail.com> writes:
>>> On Aug 9, 11:02 pm, David Lyon<david.l...@preisshare.net> wrote:
>>>> Since you're talking about documentation, which is a part of python,
>>>> don't you think you should be discussing it on python-dev ?
>>> Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better
>>> idea, lets go to the IRS and see if we can persuade them to stop
>>> taxing us...
>>
>> You know, the most interesting thing in this thread is certainly its
>> title : « Social problems of Python doc »
>>
>> Yes, the little social problem here should be clear: if you have
>> complaints to voice or improvements to suggest to the Python docs, you
>> should do so on the issue tracker (*). For most topics, this is the
>> only reasonable way to signal problems to the Python developers
>> community, and so it is in most free software / open source projects.
>
> "the *only* reasonable way"? That's clearly wrong (unless you want to
> wiggle in the room provided by "reasonable" or "most"). There is
> discussion on the dev list, there is discussion here.
Discussion here is spitting into the wind. The noise-to-signal ratio is
high enough that the people who can fix an issue aren't likely to see it
here. Unless somebody raises a report in the bug tracker, it will go
nowhere, fast.
The same happens for issues on the dev list: I can't count how many times
people there have said "put it in the bug tracker, or it will be
forgotten".
> The issue tracker is fine for many things, but the process it provides
> is equivalent to peep-hole optimization. How does one submit a tracker
> issue for something like the overall organization of the docs (for
> example, the mis-placement of things like data- types in the library
> manual rather than the language manual)?
The same way you would submit a tracker issue for anything.
"Documentation bug: Data types are misplaced in the library manual
instead of the language manual.
Suggested alternative: move page docs.python.org/xyz.html to abc.html"
> The big problem with the docs is poor writing (this includes not using
> examples when they can help explain something more clearly than verbiage
> alone).
There's a difference between insufficiently good writing and poor
writing: think of grading the docs, where 100 is "perfect in every way"
and -100 is "perfectly awful in every possible way". (It's not a linear
scale.) A score of 0 is "mediocre, just barely acceptable". Poor writing
has a negative score. In my opinion, Python's docs are perhaps a 40 or
50, significantly better than most technical docs I've seen.
[...]
> I can rewrite some section so it sounds good to me, but likely it will
> be just as bad (perhaps in different ways) that what is there.
Bug reports are valuable even if you don't have the skills to provide a
patch. Bug reports with patches are even more valuable, but that doesn't
mean that the failure to provide a patch *necessarily* dooms your report
to oblivion.
> The post that started this thread proposed something like paying
> professional writers to improve the docs. This may or may not be a
> practical suggestion. But the immediate response it engendered was an
> auto-immune-like group response: the docs are great already, don't
> complain, fix them yourself, yada, yada; the same response that any
> criticism of free software produces.
I haven't seen any such knee-jerk responses. What I've seen is a set of
sensible, *practical* advice:
- complaining on its own, especially here, is pointless;
- Python is a community effort, if you see something that needs fixing,
do something about it;
- many of us DON'T want arbitrary people "correcting" the official docs
without oversight, and believe that would be a disaster (arbitrary people
aren't give check-in privileges to add code to Python's standard library,
nor should they be given check-in privileges to add docs);
- if people are keen on a Python wiki, then by all means publish one,
just don't expect the Python dev team to build and manage it for you;
- bug reports and patches to the docs are ALWAYS welcome, even if they
are rejected;
- if you don't have the skills to fix a bug (including doc bugs), an
alternative is to pay somebody else to do so instead.
> It's really too bad the the python community can't seriously discuss
> ways to improves the docs. There are other possibilities for instance
> the Fedora Docs project (can't say I'm impressed by what they've
> produced but that doesn't mean their model is useless). There is a need
> for an approval process managed by someone who actually understands what
> good technical writing is. And perhaps editors who can polish or work
> with programmers who provide the raw technical description of some
> module.
Yes, you're correct.
[sarcasm] Now that we've agreed on what needs to be done, the problem is
solved!!! [end sarcasm]
> Some kind of higher level more global process is the only way I can see
> that the docs will be improved to any sort or professional standard. I
> don't see how issues like this will be addressed by submitting tracker
> items.
You want community input into the docs, but you're not willing to give
that input except to bitch and moan and sook that the tracker is no good.
Even if the PSF had a full-time team of professional documentation
writers and editors, guess what, you would STILL need to submit issues to
the bug tracker, because otherwise THEY WON'T BE TRACKED.
> Personally, I have given up on this issue. The social factors involved
> really pretty much determine that the Python docs will never reach a
> very high quality -- that's just the way it is and I've come to accept
> that.
Ultimately it boils down to two factors:
Money.
Effort.
If you won't put in the effort, and you won't put in the money, then it
won't happen. Moaning that other people aren't putting in the money to
hire team of professional writers isn't productive, and moaning that
other people aren't putting in the effort to improve the docs isn't
either.
--
Steven
Paul Rubin
> just don't expect the Python dev team to build and manage it for you;
There are already some nice ones at:
Raymond Hettinger
> I think the Python tutorial is aimed at users who are newbies to
> Python but not newbies to programming. Writing a tutorial for total
> newbies is a completely different problem, that would result in a much
> different document that's less useful to the existing tutorial's
> intended audience.
There is more than one right answer to "what is the best tutorial
for different people". The www.python.org website lists a number
of tutorials. Here is the page specifically marked for those
who are new to programming:
http://wiki.python.org/moin/BeginnersGuide
Raymond
Paul Rubin
> Some say the tutorial is not meant for non-programmers, but for
> programmers with no Python experience. So! How does that justify
> obstruction of the tut? Why not present the same information in a way
> both can easily understand?
I agree that a tutorial for non-programmers would be useful, but it's
better to have it as a separate document. The existing tutorial helps
experienced programmers get started with Python very quickly, by
checking off familiar features from other languages and saying how
Python implements them. Someone familiar with (say) Java or C++ can
read it in a few minutes and start contributing to a Python project.
Pitching it to complete beginners would require covering a lot of
ground that is already well known to someone who programs in other
languages, and would slow it down too much.
Paul Rubin
> Here is the page specifically marked for those who are new to programming:
> http://wiki.python.org/moin/BeginnersGuide
Oh cool, I didn't know about that one.
max bianco
D'Aprano<st...@remove-this-cybersource.com.au> wrote:
> On Fri, 07 Aug 2009 13:35:26 -0700, Kee Nethery wrote:
>
>
>> > Why exactly is posting an open comment on a bug tracker somehow
>> > inferior to posting an open comment on a wiki?
>>
>> It's a good question and deserves a good answer.
>>
>> * Fewer Steps
>> * Immediate
>> * Does not need to be formally reviewed
>> * Easier to search
>
> The last one is actually wrong, because the Python bug tracker is indexed
> by Google.
>
> As for the rest, you're right that the current bug-tracker puts up
> barriers to people submitting comments and bugs. That's actually a good
> thing. The only thing worse than not enough information is too much
> information, and the current situation does a good job of discouraging
> the sorts of people who submit bad bug reports (e.g. duplicates of bug
> reports, bug reports for things fixed years ago, bug reports that are due
> to mistakes in their code, etc.).
>
>
>> For example
>> purposes, I'll use the following page:
>> http://docs.python.org/reference/lexical_analysis.html
>> Lets say the user is in section 2.1.3 Comments
>
> Disclaimer: python.org is down at the moment, so I can't check that page
> to see precisely what you're talking about.
>
>
>> Here's the scenario: The user wanted to include "#" in one of their
>> strings and the IDE kept interpreting it as a comment. But they really
>> need to use that character in the string. Eventually they find out that
>> they can escape the character in their string so that Python stops
>> thinking it is the beginning of a comment.
>
> Er, that would be a bug in the IDE, surely? Inside strings, # is an
> ordinary character with no special meaning.
>
>
>>>> s = "this is a string with an unescaped # in it"
>>>> s
> 'this is a string with an unescaped # in it'
>
>
> The Python docs are supposed to be about Python the language, not work-
> arounds for IDE bugs.
>
>
> [...]
>> Lets assume that Python experts all agree that
>> the docs should get updated with this gotcha (which as a newbie, they
>> are not sure that is a valid assumption and would probably just halt
>> in their quest to get the docs updated).
>
> Good.
>
> As a newbie, you SHOULD assume that anything you think is a bug is
> probably a bug in YOUR code, not Python, and the same goes for
> documentation bugs. If you don't understand something in the docs,
> chances are that it's a problem with you, not the docs. Your first port
> of call should be the tutor list, or here, and not to "fix" the docs by
> putting in noise that just gets in the way of the intended audience,
> namely experienced developers.
>
I assume I am misunderstanding you here and you meant something else?
Python is paraded as a good language for beginners. Is this a false
statement or a secondary objective? Or are the docs only meant for
experienced developers? That just doesn't sound right.
Grant Edwards
> r <rt8...@gmail.com> writes:
>> Some say the tutorial is not meant for non-programmers, but for
>> programmers with no Python experience. So! How does that justify
>> obstruction of the tut? Why not present the same information in a way
>> both can easily understand?
>
> I agree that a tutorial for non-programmers would be useful, but it's
> better to have it as a separate document.
There are plenty of docs aimed at non-programmers. I've heard
this one recommended many times:
http://www.greenteapress.com/thinkpython/
--
Grant Edwards grante Yow! Am I having fun yet?
at
visi.com
max bianco
> As someone trying to learn the language I want to say that the tone on this
> list towards people who are trying to learn Python feels like it has become
> anti-newbies.
>
> Learning a new language is difficult enough without seeing other newbies
> getting shamed for not knowing everything there is to know about Python
> before asking their questions.
Well I have to say your right about the tone but using google before
you ask is not an unreasonable expectation. I have of course broken
this golden rule myself on mailing lists myself , however a response
like use google is totally acceptable to me.
Grant Edwards
> I assume I am misunderstanding you here and you meant something else?
> Python is paraded as a good language for beginners.
I believe it is a good language for beginners.
> Is this a false statement or a secondary objective?
Objective of what?
> Or are the docs only meant for experienced developers?
Some are, some aren't. The "standard" docs (most of the docs
you can reach directly from http://www.python.org/doc/ --
including the tutorial) aren't intended to teach somebody how
to program and assume the reader has a basic grounding in
programming and language theory.
There are plenty of books and tutorials that are aimed at
teaching programming and Python at the same time. You can find
some of via the links listed under "Additional documentation"
at http://www.python.org/doc/ -- particularly here:
http://wiki.python.org/moin/BeginnersGuide/NonProgrammers
> That just doesn't sound right.
--
Grant Edwards grante Yow! My mind is making
at ashtrays in Dayton ...
visi.com
r
"Tutorial" link. What is this FLUFF doing here!?!?! Where is the damn
index? Where is the damn tutorial? I want to learn Python not read the
HISTORY OF THE WORLD.
Upon clicking the "Tutorial" link pre 2.6, a nice menu was placed
before your eyes, WHERE IS IT!?!??? Good thing i know the language or
i would have given up already!!!!
Mark Lawrence
because I have a computing IQ of approximately 2**32, so realised that
something was wrong, went here and downloaded the corrected version of
the file, which has presumably been available for months!!!!!
http://www.python.org/download/releases/2.6.2/
And you want newbies let loose on the python docs. As good ole Santa
would say, ho, ho, ho!
r
folks at Python dev rolling a new installer as we speak, or we must
wait for new version?
Mark Lawrence
available for months.
ru...@yahoo.com
> On Tue, 11 Aug 2009 07:57:28 -0700, rurpy wrote:
>
>> On 08/11/2009 01:47 AM, Antoine Pitrou wrote:
>>> r<rt8396<at> gmail.com> writes:
>>>> On Aug 9, 11:02 pm, David Lyon<david.l...@preisshare.net> wrote:
>>>>> Since you're talking about documentation, which is a part of python,
>>>>> don't you think you should be discussing it on python-dev ?
>>>> Yea, them's be a friendly bunch to noob ideas ;). Hey i got a better
>>>> idea, lets go to the IRS and see if we can persuade them to stop
>>>> taxing us...
>>> You know, the most interesting thing in this thread is certainly its
>>> title : « Social problems of Python doc »
>>>
>>> Yes, the little social problem here should be clear: if you have
>>> complaints to voice or improvements to suggest to the Python docs, you
>>> should do so on the issue tracker (*). For most topics, this is the
>>> only reasonable way to signal problems to the Python developers
>>> community, and so it is in most free software / open source projects.
>> "the *only* reasonable way"? That's clearly wrong (unless you want to
>> wiggle in the room provided by "reasonable" or "most"). There is
>> discussion on the dev list, there is discussion here.
>
> Discussion here is spitting into the wind. The noise-to-signal ratio is
> high enough that the people who can fix an issue aren't likely to see it
> here. Unless somebody raises a report in the bug tracker, it will go
> nowhere, fast.
The point isn't always to gain a core developer's attention --
sometimes it is to figure out a good approach before proposing
something concrete.
> The same happens for issues on the dev list: I can't count how many times
> people there have said "put it in the bug tracker, or it will be
> forgotten".
On the contrary, there are many issues raised there that are
discussed there or result in the response, "take it to python-
ideas". Not every issue to so well-baked that it is ready for
a tracker issue with patch. There are some things that need
discussion before investing a lot of effort in them.
>> The issue tracker is fine for many things, but the process it provides
>> is equivalent to peep-hole optimization. How does one submit a tracker
>> issue for something like the overall organization of the docs (for
>> example, the mis-placement of things like data- types in the library
>> manual rather than the language manual)?
>
> The same way you would submit a tracker issue for anything.
>
> "Documentation bug: Data types are misplaced in the library manual
> instead of the language manual.
>
> Suggested alternative: move page docs.python.org/xyz.html to abc.html"
But that's the problem. Such a reorg is not a simple matter
of moving a file from here to there. It will require a lot
moving about of sections and a lot of word-smithing to glue
them back together again in a coherent way.
A tracker issue, even one that was fairly specific about
how things should be reorganized but which did not provide
all the needed changes (a large patch) would almost certainly
be ignored or rejected. But providing a large patch raises
two questions. How likely is it to be be accepted?
(Something anyone would want to know before investing the time.)
And how to actually do the work needed to generate it (it could
be a very large amount of work for an individual and I don't
think it can be broken down into small independent issues.)
How is one to test the waters as to acceptability, or solicit
help, if one simply submits a tracker issue?
>> The big problem with the docs is poor writing (this includes not using
>> examples when they can help explain something more clearly than verbiage
>> alone).
>
> There's a difference between insufficiently good writing and poor
> writing: think of grading the docs, where 100 is "perfect in every way"
> and -100 is "perfectly awful in every possible way". (It's not a linear
> scale.) A score of 0 is "mediocre, just barely acceptable". Poor writing
> has a negative score. In my opinion, Python's docs are perhaps a 40 or
> 50, significantly better than most technical docs I've seen.
There is no objective way of rating docs. My evaluation results
in part from the fact that I was able to learn Perl using only
the man pages. I seriously attempted the same with the supposedly
easier-to-learn Python but was not able to and had to resort to
other web resources and buying Beazly's book.
Before you reply that tutorials are for learning, not reference
manuals, I will disagree. A well written reference manual will
provide all the information needed to understand a language (albeit
arranged differently than the linear form of a tutorial), and I
have learned several languages in addition to Perl from their
reference materials. Which is why I attribute my failure to do
so with Python to be the docs' fault.
> [...]
>> I can rewrite some section so it sounds good to me, but likely it will
>> be just as bad (perhaps in different ways) that what is there.
>
> Bug reports are valuable even if you don't have the skills to provide a
> patch. Bug reports with patches are even more valuable, but that doesn't
> mean that the failure to provide a patch *necessarily* dooms your report
> to oblivion.
>
>
>> The post that started this thread proposed something like paying
>> professional writers to improve the docs. This may or may not be a
>> practical suggestion. But the immediate response it engendered was an
>> auto-immune-like group response: the docs are great already, don't
>> complain, fix them yourself, yada, yada; the same response that any
>> criticism of free software produces.
>
> I haven't seen any such knee-jerk responses. What I've seen is a set of
> sensible, *practical* advice:
>
> - complaining on its own, especially here, is pointless;
I don't think that is true. (Or rather, the extent that it is true
is determined by the attitudes here.)
> - Python is a community effort, if you see something that needs fixing,
> do something about it;
Pointing out something that needs fixing *is* doing something
about it. Maybe not as much as you'd like but from each according
to his ability...
> - many of us DON'T want arbitrary people "correcting" the official docs
> without oversight, and believe that would be a disaster (arbitrary people
> aren't give check-in privileges to add code to Python's standard library,
> nor should they be given check-in privileges to add docs);
Agreed. I hope that was clear from my earlier post.
> - if people are keen on a Python wiki, then by all means publish one,
> just don't expect the Python dev team to build and manage it for you;
As luminous a Pythoneer as Fredrik Lundh set up a documentation
wiki to collect user contributions but it has faded away. If
he couldn't pull it off then I'd say most other attempts without
the backing of python.org are almost certainly doomed to failure.
However, were the Python docs site to provide a wiki, along
with a mechanism to migrate suggestions developed on the wiki
into the docs, it might well be a viable (and easier because of
the wysiwyg effect) way of improving the docs. As other have
pointed out, Postgresql, PHP, and Haskell have done so.
Now maybe there are good reasons not to do that. But your hand-
waving is not one of them.
> - bug reports and patches to the docs are ALWAYS welcome, even if they
> are rejected;
Of course. The cost for briefly looking at a report before
rejecting it is very low. However the cost for producing it
can be much higher. I'm not saying that that is what happens,
just that your statement considers only the pov of the issue
handlers, not the submitters.
> - if you don't have the skills to fix a bug (including doc bugs), an
> alternative is to pay somebody else to do so instead.
That there are alternatives was not my point. My point was
that there are perhaps *other* alternatives too, but anyone
who tries to explore them here usually gets buried under a
mass of negativity.
>> It's really too bad the the python community can't seriously discuss
>> ways to improves the docs. There are other possibilities for instance
>> the Fedora Docs project (can't say I'm impressed by what they've
>> produced but that doesn't mean their model is useless). There is a need
>> for an approval process managed by someone who actually understands what
>> good technical writing is. And perhaps editors who can polish or work
>> with programmers who provide the raw technical description of some
>> module.
>
> Yes, you're correct.
>
> [sarcasm] Now that we've agreed on what needs to be done, the problem is
> solved!!! [end sarcasm]
Anyone who's ever been to AA knows that the first step to
solving a problem is to acknowledge the problem exists.
As long as every "the docs sux" complaint is met here with
the standard responses that I've mentioned, rather than, "yes,
they do have some problems, what do you think we should do
about them?", the docs will continue to sux. But as I said
maybe that's just the way it is.
>> Some kind of higher level more global process is the only way I can see
>> that the docs will be improved to any sort or professional standard. I
>> don't see how issues like this will be addressed by submitting tracker
>> items.
>
> You want community input into the docs, but you're not willing to give
> that input except to bitch and moan and sook that the tracker is no good.
I have not done any "bitching and moaning". I tried to
explain a group reaction that affects python negatively
(IMO) by rejecting any consideration of ways of improving
the docs other than submitting tracker issues.
That you pejoratively label it "bitching and moaning"
I count as evidence supporting my view.
> Even if the PSF had a full-time team of professional documentation
> writers and editors, guess what, you would STILL need to submit issues to
> the bug tracker, because otherwise THEY WON'T BE TRACKED.
Maybe, maybe not. Depends on what development process the
(hypothetical) doc team chooses to use is.
>> Personally, I have given up on this issue. The social factors involved
>> really pretty much determine that the Python docs will never reach a
>> very high quality -- that's just the way it is and I've come to accept
>> that.
>
> Ultimately it boils down to two factors:
>
> Money.
>
> Effort.
>
> If you won't put in the effort, and you won't put in the money, then it
> won't happen. Moaning that other people aren't putting in the money to
> hire team of professional writers isn't productive, and moaning that
> other people aren't putting in the effort to improve the docs isn't
> either.
Eh? I have a computer filled with software that I put no
money or effort into, yet there it is. So clearly you are
wrong in the general sense. Before you call me a free-loading
ingratiate consider the software you use and how much of it you
have made substantive contributions to. We all have limited
time and resources and we all have to choose where to invest that
time. That some of us choose to invest it somewhere other than
Python does not deprive of of our right to point out problems
in Python when we note them.
Mark Lawrence
> On Aug 11, 1:46 pm, Mark Lawrence <breamore...@yahoo.co.uk> wrote:
>> r wrote:
>>> Ah Ha! the docs are broken and i was right all along! Are the good
>>> folks at Python dev rolling a new installer as we speak, or we must
>>> wait for new version?
>> As I pointed out a few minutes ago thicko, the new version has been
>> available for months.
>
>
>
> I'm mailing you to kindly request, again, that you please stop
> validating "r"'s disruptiveness by responding to him on
> comp.lang.python. Thank you.
>
> Carl Banks
I hereby apologise. My only feeble excuse is that my mammary glands are
getting crushed.
Paul Boddie
>
> However, were the Python docs site to provide a wiki, along
> with a mechanism to migrate suggestions developed on the wiki
> into the docs, it might well be a viable (and easier because of
> the wysiwyg effect) way of improving the docs. As other have
> pointed out, Postgresql, PHP, and Haskell have done so.
> Now maybe there are good reasons not to do that. But your hand-
> waving is not one of them.
I think you make some good points, although I don't have time to
respond to all of them. Certainly, the documentation situation with
Python is not ideal; otherwise, people would not be complaining about
it so frequently.
I recommend going to the existing Wiki and looking at what there is
already:
http://wiki.python.org/moin/Documentation
http://wiki.python.org/moin/CategoryDocumentation
Sadly, I don't think you'll find much to work with, apart from the
occasional attempt to make an annotated version of the existing
documentation:
http://wiki.python.org/moin/PythonLibraryReference
So my next recommendation is to either use the existing Wiki
infrastructure or to ask for a separate Wiki for the purpose of
reworking the documentation. You could either take the existing
documentation, which I believe is now restructured text, and just drop
that into the Wiki with the appropriate format directives (for later
reworking in Wiki format, perhaps), or you could start afresh and
tackle some of the more serious issues head on.
I can see benefits to just starting from scratch. Perhaps the
licensing should be more explicit than the existing material on the
Wiki so that the documentation produced could be freely distributed
without uncertainty, but the outcome would hopefully be something that
stands on its own as an alternative or a replacement to the
conventional documentation.
Paul
r
> > I'm mailing you to kindly request, again, that you please stop
> > validating "r"'s disruptiveness by responding to him on
> > comp.lang.python. Thank you.
Carl,
You have no right to tell people when where and how they should speak
to anyone. And how dare you think you can! If you spent even a
fraction of the time you spend manipulating the direction of this list
and instead, actually contributing to the problem at hand, (discussion
or otherwise) we would be much closer to solving this problem today.
You (and your conspirators) are the reason most people find the c.l.py
list so disturbing and wish not to participate. Get a life you moron
and stop trying to control the world.
PS: GET STUFFED!