Python docs disappointing

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

Well to a level I agree with you. [snip]
have an adversity for looking up resources using a web browser

It may not be an adversity for looking things up using a
web-browser, but rather the need to access documentation offline.
Whether on an airplane or simply away from a wifi/landline
connection, there are plenty of times I'm coding offline (another
reason I'm happy to have DVCS tools).

This thread prompted me to go digging a little further, and all
the online docs are available in downloadable format, but you
have to start by going to the base docs and chasing down the
"downloads" rabbit-hole. Perhaps it would be easier if there
were some sort of back-link from individual pages, referencing
the downloadable format package.

Combined with the downloaded HTML version of the docs (there are
PDFs too if you prefer), using a lightweight browser like
lynx/links/dillo, and optionally adding htdig for local
search/indexing, you can access (and search) the full docs offline.

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

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

 

[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]

Hi Tim

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]

update: if I set 'use KHTMLPart-based widget' instead of 'QTextBrowser-
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 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.

 

[Ethan Furman]

Please don't feed the trolls.

And if you do feed the trolls don't smile at them.


Carl Banks

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]

I've brought up the idea of the quasi-community doc that PHP uses to
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]

And what have you done about setting up such a project?


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.

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]

http://www.php.net/manual/en/language.types.array.php is a prime example
[ ... ]

I consider consider this to an unreadable mishmash. [compared to]
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?)

 

[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]

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!

 

[Kee Nethery]

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.

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