Re: Do you feel bad because of the Python docs?

[Terry Reedy]

On 3/8/2013 11:12 PM, Bob Hanson wrote:


I do notice trivial changes,


I am currently set up again to do doc changes, so if you already have 
some non-controversial changes to the *current* docs, the online html 
versions, go ahead and email them to me.



but I also feel some of the
documentation could benefit from a much more thorough general
editing to improve both ease of reading and general clarity.


Big edits will need discussion on the tracker and will likely be opposed 
by someone.



Contributing in this way sounds like I'll want to get more
involved and probably do the contributor-signing thing and such
-- or whatever steps I need to follow.


Please do the agreement thing now. We just added the e-form a week ago 
and with that are getting more serious about asking for the agreements.


--
Terry Jan Reedy

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Bob Hanson]

On Wed, 06 Mar 2013 18:50:35 -0500, Terry Reedy wrote:

> On 3/6/2013 2:48 PM, rh wrote:
> 
> > [Bob Hanson wrote:]
> >
> > > I've tried twice to register with the bug tracker -- including
> > > just before sending this post. [...]
> > >
> > > [other details and errors snipped] 
> > >
> > > I had wanted to report doc bugs, too, as I used to do copy and
> > > line editing. I seem to be able to find typos and such rather
> > > easily, but reporting said bugs -- not so easy.
>
>  From http://docs.python.org/3/bugs.html
> 
> "Documentation bugs
> 
> If you find a bug in this documentation or would like to propose an 
> improvement, please send an e-mail to d...@python.org describing the bug 
> and where you found it. If you have a suggestion how to fix it, include 
> that as well.
> 
> d...@python.org is a mailing list run by volunteers; your request will 
> be noticed, even if it takes a while to be processed."
> 
> For anything more than trivial changes (typos, grammar errors), a 
> tracker issue is better. But the above is better than nothing.

Thanks, Terry. I've been wanting to contribute for years, but a
variety of issues (details of which are not relevant here) makes
my helping improve the documentation probably the best fit for my
abilities and situation.

I do notice trivial changes, but I also feel some of the
documentation could benefit from a much more thorough general
editing to improve both ease of reading and general clarity. 

Contributing in this way sounds like I'll want to get more
involved and probably do the contributor-signing thing and such
-- or whatever steps I need to follow.

And again, sorry for the late reply -- I was without internet for
a few days while I changed ISPs.

Regards,
Bob Hanson

-- 
Don't take yourself serious -- or no one else will.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Chris Angelico]

On Sat, Mar 9, 2013 at 2:31 PM, Bob Hanson  wrote:
> (I was without internet access for a few days while the experts
> at the phone company once again attempted to simulate minimal
> competence culminating with their "DSL install expert" -- who had
> never heard of Linux -- trying to puzzle out my desktop.)

I know exactly how that feels. Back in 2002 or thereabouts when we got
our current Optus cable connection installed, we were an all-OS/2 shop
(and we still have a good bit of OS/2, but there's some Windows and a
good bit of Linux around now too). Rather than go through the hassle
of having the guy try to figure out OS/2, we just rigged up a
temporary Windows box and let him have his fun. Soon as he'd left, we
unplugged the network cable from that machine and plugged it into our
router (and then did a MAC address clone in the router, as for some
reason the device was set to accept traffic only from the NIC the tech
had installed).

Funny, though, that Linux is still able to be obscure.

ChrisA
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Bob Hanson]

On 06 Mar 2013 03:38:36 GMT, Steven D'Aprano wrote:

> On Tue, 05 Mar 2013 17:51:36 -0800, Bob Hanson wrote:
> 
> > [trouble reporting bugs]
> 
> Works for me.
> 
> Please try again, and if it still does not work, please email me off-list 
> and I will help you either set up an account or report a tracker bug.

Thanks, Steven. I'll likely take you up on your offer to help me
off-list via email as I also wanted to talk with you about your
circular-means function in your stats package.

I do want to help with doc bugs. I'll probably have to get fairly
involved to be able to submit more major doc-bug patches -- as
others have said.

And, as I said to Mark, sorry for the late reply. 

(I was without internet access for a few days while the experts
at the phone company once again attempted to simulate minimal
competence culminating with their "DSL install expert" -- who had
never heard of Linux -- trying to puzzle out my desktop.)

Regards,
Bob Hanson

-- 
Sent by smoke signals from the top of Mount St. Helens. Please
excuse the sulfur fumes.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Bob Hanson]

On Wed, 06 Mar 2013 03:12:43 +, Mark Lawrence wrote:

> On 06/03/2013 01:43, Bob Hanson wrote:
>
> > [problem reporting bugs]
> 
> You'll be delighted to know that everybody will have to sign a 
> contributor agreement if they're supplying a patch file on the bug 
> tracker, see 
> http://blog.python.org/2013/03/introducing-electronic-contributor.html 
> and http://mail.python.org/pipermail/python-dev/2013-March/124540.html

Thanks, Mark. I have other responses to reply to, as well. I
suspect that between your advice and the others, I'll learn how
to help with at least doc bugs, soon.

And sorry for the late reply. I changed ISPs (dialup to DSL)
which turned out to be a major... uh... event for the geniuses at
the telephone company out here in the "frontier" of the Oregon
Cascades.

Regards,
Bob Hanson

-- 
Sent from my Smart shoephone. Please excuse failure to top-post,
failure to snip-to-context, and failure to leave message-digest
subject header intact.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Rick Johnson]

On Wednesday, March 6, 2013 9:12:37 PM UTC-6, alex23 wrote:

> Your obsession with Guido is tiring. 

And your false accusations that i am somehow "obsessed" with GvR have BEEN 
tiring for quite some time! I am neither passionate for or prejudice against 
the man. I simple ask that he live up to his job title.

> Open source is not a cult of
> personality. It's about doing what you can where you can when you can
> to make things better. Insisting that he "endorse" your ideas is
> ridiculous.

Of course insisting that he validate me *personally* would be ridiculous. But i 
am NOT suggesting that he validate ME, i am suggesting that he do his job. And 
his job is to oversee the language evolution and maintain a sense of community. 
Specifically: "leading by example". 

Q: "Why even have a python-list if GvR and all the "heavies" at py-dev never 
participate in the conversations?"

By NOT participating they are speaking louder than words.

> Third party modules will never be handled by the Python bug tracker,
> nor should they be lumped into the same "path"; they're the concern of
> their developers 

I agree, that was an unfortunate typo.

> If you have ideas for improvement, _then implement them_. The crate.io
> guys didn't wait for community validation to address what they
> perceived were issues with PyPI, they rolled up their sleeves and did
> something about it.

Great, and i commend the contribution. But is yet ANOTHER Python package list 
going to help anyone? How about 10 or 20 more Python package indexes? 

Community fragmentation and language forks due to core-dev stubbornness is 
unfortunate. I would much rather had them contribute to the existing package 
index instead of creating a new one. 

Congratulations Alex, your solution of pushing everyone away is working 
flawlessly -- just don't be surprised when you find yourself cold and alone.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[alex23]

On Mar 7, 12:57 pm, Rick Johnson  wrote:
> GvR DOES NOT need to mention my name. All i am asking is that he show
> some support for the general *idea* of "lowering the bar for bug/grievance
> reporting". Or at least start by admitting we have a problem.

Your obsession with Guido is tiring. Open source is not a cult of
personality. It's about doing what you can where you can when you can
to make things better. Insisting that he "endorse" your ideas is
ridiculous.

> Secondly: The "report bugs" feature of the doc is more concerned with
> "doc related" bugs.

It would really help your arguments if you actually spent some time
investigating the issues you're ranting against:

http://docs.python.org/3/bugs.html

Documentation bugs are a brief paragraph at the top of the page, the
rest of which addresses bugs with the language & standard library.

> I want a holistic approach that will invite ALL Python related issues (docs,
> language, community, modules, 3rd party modules, etc...) to follow a linear 
> path.

Third party modules will never be handled by the Python bug tracker,
nor should they be lumped into the same "path"; they're the concern of
their developers who shouldn't be bound by your desire for a One True
Way. Community "bugs" should be addressed on the python list.

> My point is that we

You keep saying "we" when you mean other people apart from yourself.
If you have ideas for improvement, _then implement them_. The crate.io
guys didn't wait for community validation to address what they
perceived were issues with PyPI, they rolled up their sleeves and did
something about it.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Rick Johnson]

On Wednesday, March 6, 2013 8:28:42 PM UTC-6, alex23 wrote:
> On Mar 7, 11:31 am, Rick Johnson  wrote:
> > I don't have a low opinion of anybody here. However the fact that
> > this community needs an entry level path for bug/grievance reports
> > is *glaringly* obvious.
> 
> Please explain how finding your vanity list would be easier than
> reading the Python doc's table of contents and clicking on the entry
> "Reporting Bugs".

Firstly: It's not a "Rick's Vanity List" unless my name is on it. I don't 
expect to be named the "BDFL of PyWarts". Heck, i don't even expect to be 
"named" at all. GvR DOES NOT need to mention my name. All i am asking is that 
he show some support for the general *idea* of "lowering the bar for 
bug/grievance reporting". Or at least start by admitting we have a problem. 

Secondly: The "report bugs" feature of the doc is more concerned with "doc 
related" bugs. I want a holistic approach that will invite ALL Python related 
issues (docs, language, community, modules, 3rd party modules, etc...) to 
follow a linear path.

There may be better ways of achieving my goals (f.e. Terry proposed a great 
idea). My point is that we need to lower the bar and try to integrate a linear 
path that will allow all levels of Python programmers to participate. 
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Chris Angelico]

On Thu, Mar 7, 2013 at 12:31 PM, Rick Johnson
 wrote:
> We need to know where the bottle necks are when learning the language, and 
> since we are experienced, we lack the noob insight to even see the problems. 
> I'll bet $100 you hated writing self as the first argument to each method. 
> But now you've become so accustomed that you could so it in your sleep.

Gambling debts are due within twenty-four hours. Please remit that
hundred dollars immediately; I had absolutely no problem with the
explicit 'self' argument.

Thanks, it's about time I earned some money arguing with you.

ChrisA
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Rick Johnson]

On Wednesday, March 6, 2013 7:52:59 PM UTC-6, Terry Reedy wrote:

>  > How much longer are we going to "treat the symptoms"
> 
> We would VERY MUCH like a system to make it easier for readers to report 
> doc bugs and developers to fix them. No one yet has come up with both a 
> reasonable idea and workable implementation. Here is an idea I just came 
> up with.
> 
> *Someone* writes javascript that allows the following: Reader using the 
> web version sees a mistake, selects some text with the mistake, right 
> clicks, selects 'Suggest correction', gets a box or form with the 
> selected text, page and location or context info, and a text entry box. 
> Reader enters correction in text box and clicks OK. Message is emailed 
> or posted to python.org.

YES, YES, YES! This is even better than "PyWarts" because the user will not 
need to log onto a forum and then compose a post. In effect, the forum will 
come to him! I love it!

However, there is a dark-side on the opposite side of this mountain. Your idea 
solves "doc related" issues, but what about "language related" issues? I still 
love your idea, however, i am looking for a holistic approach to solving the 
issue. 

> *Someone* writes a python script to process reports by generating a 
> proposed patch for human review.

Also, i would like to add. That all user submitted "reports" should be posted 
in a searchable database somewhere that is public; so we can keep track of 
which parts of the docs (or language) are creating the highest volume of 
complaints\bugs. 
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[alex23]

On Mar 7, 11:31 am, Rick Johnson  wrote:
> I don't have a low opinion of anybody here. However the fact that
> this community needs an entry level path for bug/grievance reports
> is *glaringly* obvious.

Please explain how finding your vanity list would be easier than
reading the Python doc's table of contents and clicking on the entry
"Reporting Bugs".
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Michael Ross]

On Thu, 07 Mar 2013 02:28:10 +0100, Chris Kaynor  
 wrote:



I actually just tried that, and the results weren't very good.

Using the doc's search feature, the "Reporting Bugs" (and the "About  
these documents") page >was significantly down the page (about 2/3 of  
the way) - not the most obvious result in the pile. All the >other  
searches I could think of either didn't return either of those pages at  
all, or they were also 1/2-2/3 >of the way down the page.





Using Google it took me about 3 seconds to find the page.

"python report doc bug".

Works with Bing or DuckDuckGo too. First hit on either engine.

The doc's search is ... fine if I search for e. g. 'subprocess.Popen',
but near-useless for general searches.




The link is also on the main documentation page, but it is, again, near  
the bottom, making it hidden from >many users. Both of them show up just  
above the bottom of the window with it maximized on my screen.




The first of the issues may be difficult to fix,


Is it?
You'd just have to have an additional search box labeld "search whole page  
with google/bing/whatever" (?)





but would likely be fairly useful - that would generally be my first  
port of call. The second one is more >minor as most people will scroll  
down to see whats farther down, if they go to the main page to find the  
>links.




Chris



On Wed, Mar 6, 2013 at 5:06 PM, alex23  wrote:



On Mar 7, 10:47 am, Rick Johnson  wrote:


That's great Terry, but how will the next person find the link?




Why do you have such a low opinion of others that you think they're

unable to look up "Reporting Bugs" in the _documentation_?

--

http://mail.python.org/mailman/listinfo/python-list




--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Terry Reedy]

On 3/6/2013 7:47 PM, Rick Johnson wrote:

On Wednesday, March 6, 2013 5:50:35 PM UTC-6, Terry Reedy wrote:


If you find a bug in this documentation or would like to propose an
improvement, please send an e-mail to d...@python.org describing the bug
and where you found it. If you have a suggestion how to fix it, include
that as well.


That's great Terry, but how will the next person find the link?


The same way I did. Go to http://docs.python.org/3/ (or /2/ and click on 
Reporting bugs, which takes one to the above and more.


> I went to Python.org and i did not see it on the home page, nor the 
doc page...


Which doc page?

> How much longer are we going to "treat the symptoms"

We would VERY MUCH like a system to make it easier for readers to report 
doc bugs and developers to fix them. No one yet has come up with both a 
reasonable idea and workable implementation. Here is an idea I just came 
up with.


*Someone* writes javascript that allows the following: Reader using the 
web version sees a mistake, selects some text with the mistake, right 
clicks, selects 'Suggest correction', gets a box or form with the 
selected text, page and location or context info, and a text entry box. 
Reader enters correction in text box and clicks OK. Message is emailed 
or posted to python.org.


*Someone* writes a python script to process reports by generating a 
proposed patch for human review.


--
Terry Jan Reedy

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Rick Johnson]

On Wednesday, March 6, 2013 7:06:56 PM UTC-6, alex23 wrote:
> Why do you have such a low opinion of others that you think they're
> unable to look up "Reporting Bugs" in the _documentation_?

I don't have a low opinion of anybody here. However the fact that this 
community needs an entry level path for bug/grievance reports is *glaringly* 
obvious. It would greatly benefit this community by:

1. Removing excess chatter from the bug tracker. 

We need to keep the tracker folks focused on *real* bugs that can be patched. 
Not engaged in endless discussions on the semantics of "what is a bug" and what 
"IS NOT a bug".

2. Removing barriers to reporting bugs/grievances. 

Remember, if reporting issues is too difficult, people will just give up. Then, 
the next person who gets slammed with the same problem will go through the same 
trouble only to produce no results AGAIN. Rinse and repeat!

3. Give us insight as to what aspects of the language/docs are troubling for 
folks. 

We need to know where the bottle necks are when learning the language, and 
since we are experienced, we lack the noob insight to even see the problems. 
I'll bet $100 you hated writing self as the first argument to each method. But 
now you've become so accustomed that you could so it in your sleep. That does 
not validate the asininity of doing such a thing! How can we fix entry-level  
problems if we DON'T KNOW WHAT THE PROBLEMS ARE!

4. Create a *real* sense of community.

By creating a place for people to voice complaints, we are letting them know 
that "Hey, you opinion is important to us, even if you are a total NOOB!". Even 
if their "pet problem" is never solved (maybe because it was a misunderstanding 
all along), they are more likely to get involved more deeply in Python 
community later on. Heck, maybe they will work their way up to py-dev and rub 
shoulders with GvR one day, "the skys the limit"!

I have already offered my assistance managing such a list. But i cannot start 
such a list without wide community support; I cannot start the list without GvR 
publicly supporting it; I cannot start the list without a prominent link on 
python.org; because if i do start a list without all these things, i will be 
wasting my time. 
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Chris Kaynor]

I actually just tried that, and the results weren't very good.

Using the doc's search feature, the "Reporting Bugs" (and the "About these
documents") page was significantly down the page (about 2/3 of the way) -
not the most obvious result in the pile. All the other searches I could
think of either didn't return either of those pages at all, or they were
also 1/2-2/3 of the way down the page.

The link is also on the main documentation page, but it is, again, near the
bottom, making it hidden from many users. Both of them show up just above
the bottom of the window with it maximized on my screen.

The first of the issues may be difficult to fix, but would likely be fairly
useful - that would generally be my first port of call. The second one is
more minor as most people will scroll down to see whats farther down, if
they go to the main page to find the links.

Chris


On Wed, Mar 6, 2013 at 5:06 PM, alex23  wrote:

> On Mar 7, 10:47 am, Rick Johnson  wrote:
> > That's great Terry, but how will the next person find the link?
>
> Why do you have such a low opinion of others that you think they're
> unable to look up "Reporting Bugs" in the _documentation_?
> --
> http://mail.python.org/mailman/listinfo/python-list
>
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[alex23]

On Mar 7, 10:47 am, Rick Johnson  wrote:
> That's great Terry, but how will the next person find the link?

Why do you have such a low opinion of others that you think they're
unable to look up "Reporting Bugs" in the _documentation_?
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Rick Johnson]

On Wednesday, March 6, 2013 5:50:35 PM UTC-6, Terry Reedy wrote:

> If you find a bug in this documentation or would like to propose an 
> improvement, please send an e-mail to d...@python.org describing the bug 
> and where you found it. If you have a suggestion how to fix it, include 
> that as well.

That's great Terry, but how will the next person find the link? I went to 
Python.org and i did not see it on the home page, nor the doc page... and i've 
been Python-ing for years now! 

If i can't find the link, how will a noob find it? How much longer are we going 
to "treat the symptoms" before we realize that we're dealing with a disease 
that can be cured?
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Terry Reedy]

On 3/6/2013 2:48 PM, rh wrote:


I've tried twice to register with the bug tracker -- including
just before sending this post. Both times I got something like
this:

 Subject: Failed issue tracker submission
 From: Python tracker 
 Date: Wed, 06 Mar 2013 00:56:44 +

 An unexpected error occurred during the processing
 of your message. The tracker administrator is being
 notified.

So, it's not all that easy to report bugs for me, anyway. I'd
given up, prior, but reading this thread I thought I'd try one
more time.

I had wanted to report doc bugs, too, as I used to do copy and
line editing. I seem to be able to find typos and such rather
easily, but reporting said bugs -- not so easy.


From http://docs.python.org/3/bugs.html

"Documentation bugs

If you find a bug in this documentation or would like to propose an 
improvement, please send an e-mail to d...@python.org describing the bug 
and where you found it. If you have a suggestion how to fix it, include 
that as well.


d...@python.org is a mailing list run by volunteers; your request will 
be noticed, even if it takes a while to be processed."


For anything more than trivial changes (typos, grammar errors), a 
tracker issue is better. But the above is better than nothing.


--
Terry Jan Reedy

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Steven D'Aprano]

On Tue, 05 Mar 2013 17:51:36 -0800, Bob Hanson wrote:


> I've tried twice to register with the bug tracker -- including just
> before sending this post. Both times I got something like this:
> 
> Subject: Failed issue tracker submission From: Python tracker
>  Date: Wed, 06 Mar 2013
> 00:56:44 +
> 
> An unexpected error occurred during the processing of your message.
> The tracker administrator is being notified.

Works for me.


Please try again, and if it still does not work, please email me off-list 
and I will help you either set up an account or report a tracker bug.



-- 
Steven
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Mark Lawrence]

On 06/03/2013 01:43, Bob Hanson wrote:

On Wed, 27 Feb 2013 15:25:25 -0800 (PST), alex23 wrote:


On Feb 27, 1:13 pm, Rick Johnson  wrote:


[...] do you /really/ expect that people
have the time to open an issue on the bug tracker?


If someone can write a paragraph on their blog or this list
complaining about a problem, then yes, they have the time to open an
issue on the bug tracker.


I've tried twice to register with the bug tracker -- including
just before sending this post. Both times I got something like
this:

 Subject: Failed issue tracker submission
 From: Python tracker 
 Date: Wed, 06 Mar 2013 00:56:44 +

 An unexpected error occurred during the processing
 of your message. The tracker administrator is being
 notified.

So, it's not all that easy to report bugs for me, anyway. I'd
given up, prior, but reading this thread I thought I'd try one
more time.

I had wanted to report doc bugs, too, as I used to do copy and
line editing. I seem to be able to find typos and such rather
easily, but reporting said bugs -- not so easy.

Something seems amiss, I'd say. It may be just me, but the point
still stands.

--Bob Hanson



You'll be delighted to know that everybody will have to sign a 
contributor agreement if they're supplying a patch file on the bug 
tracker, see 
http://blog.python.org/2013/03/introducing-electronic-contributor.html 
and http://mail.python.org/pipermail/python-dev/2013-March/124540.html


--
Cheers.

Mark Lawrence

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Bob Hanson]

[Sorry for the double-post -- I somehow had Followup-To set to
poster in the first post.]

On Wed, 27 Feb 2013 15:25:25 -0800 (PST), alex23 wrote:

> On Feb 27, 1:13 pm, Rick Johnson  wrote:
>
> > [...] do you /really/ expect that people
> > have the time to open an issue on the bug tracker?
> 
> If someone can write a paragraph on their blog or this list
> complaining about a problem, then yes, they have the time to open an
> issue on the bug tracker.

I've tried twice to register with the bug tracker -- including
just before sending this post. Both times I got something like
this:

Subject: Failed issue tracker submission
From: Python tracker 
Date: Wed, 06 Mar 2013 00:56:44 +

An unexpected error occurred during the processing
of your message. The tracker administrator is being
notified.

So, it's not all that easy to report bugs for me, anyway. I'd
given up, prior, but reading this thread I thought I'd try one
more time.

I had wanted to report doc bugs, too, as I used to do copy and
line editing. I seem to be able to find typos and such rather
easily, but reporting said bugs -- not so easy.

Something seems amiss, I'd say. It may be just me, but the point
still stands.

--Bob Hanson

-- 
Hanson's Heuristic: Ninety-eight percent of what I think I know
is bullshit. The rest is crap.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Bob Hanson]

[Sorry for the double-post -- I somehow had Followup-To set to
poster in the first post.]

On Wed, 27 Feb 2013 15:25:25 -0800 (PST), alex23 wrote:

> On Feb 27, 1:13 pm, Rick Johnson  wrote:
>
> > [...] do you /really/ expect that people
> > have the time to open an issue on the bug tracker?
> 
> If someone can write a paragraph on their blog or this list
> complaining about a problem, then yes, they have the time to open an
> issue on the bug tracker.

I've tried twice to register with the bug tracker -- including
just before sending this post. Both times I got something like
this:

Subject: Failed issue tracker submission
From: Python tracker 
Date: Wed, 06 Mar 2013 00:56:44 +

An unexpected error occurred during the processing
of your message. The tracker administrator is being
notified.

So, it's not all that easy to report bugs for me, anyway. I'd
given up, prior, but reading this thread I thought I'd try one
more time.

I had wanted to report doc bugs, too, as I used to do copy and
line editing. I seem to be able to find typos and such rather
easily, but reporting said bugs -- not so easy.

Something seems amiss, I'd say. It may be just me, but the point
still stands.

--Bob Hanson

-- 
Hanson's Heuristic: Ninety-eight percent of what I think I know
is bullshit. The rest is crap.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Bob Hanson]

On Wed, 27 Feb 2013 15:25:25 -0800 (PST), alex23 wrote:

> On Feb 27, 1:13 pm, Rick Johnson  wrote:
>
> > [...] do you /really/ expect that people
> > have the time to open an issue on the bug tracker?
> 
> If someone can write a paragraph on their blog or this list
> complaining about a problem, then yes, they have the time to open an
> issue on the bug tracker.

I've tried twice to register with the bug tracker -- including
just before sending this post. Both times I got something like
this:

Subject: Failed issue tracker submission
From: Python tracker 
Date: Wed, 06 Mar 2013 00:56:44 +

An unexpected error occurred during the processing
of your message. The tracker administrator is being
notified.

So, it's not all that easy to report bugs for me, anyway. I'd
given up, prior, but reading this thread I thought I'd try one
more time.

I had wanted to report doc bugs, too, as I used to do copy and
line editing. I seem to be able to find typos and such rather
easily, but reporting said bugs -- not so easy.

Something seems amiss, I'd say. It may be just me, but the point
still stands.

--Bob Hanson

-- 
Hanson's Heuristic: Ninety-eight percent of what I think I know
is bullshit. The rest is crap.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Jake Angulo]

The OP speaks for himself alone.

Python - for such a very young language, and with the documentation and
community blogs available at this point - I cannot ask for more.

And who needs docs when the python syntax is as good as writing plain
english sentence?


On Fri, Mar 1, 2013 at 9:06 PM, Jean-Michel Pichavant <
jeanmic...@sequans.com> wrote:

> [snip hostile replies]
>
> It's somehow funny to read such posts on a thread about someone
> complaining about the community python being hostile.
> I think we should really try to resist the urge of answering trolls
> because no matter how many times we slap them, they'll stay trolls and
> probably get even bigger.
>
> Instead, we take revenge by helping someone asking us to do his homework
> and show the world how merciful the python community is.
>
> JM
>
>
> -- IMPORTANT NOTICE:
>
> The contents of this email and any attachments are confidential and may
> also be privileged. If you are not the intended recipient, please notify
> the sender immediately and do not disclose the contents to any other
> person, use it for any purpose, or store or copy the information in any
> medium. Thank you.
> --
> http://mail.python.org/mailman/listinfo/python-list
>
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Jean-Michel Pichavant]

[snip hostile replies]

It's somehow funny to read such posts on a thread about someone complaining 
about the community python being hostile.
I think we should really try to resist the urge of answering trolls because no 
matter how many times we slap them, they'll stay trolls and probably get even 
bigger.

Instead, we take revenge by helping someone asking us to do his homework and 
show the world how merciful the python community is.

JM


-- IMPORTANT NOTICE: 

The contents of this email and any attachments are confidential and may also be 
privileged. If you are not the intended recipient, please notify the sender 
immediately and do not disclose the contents to any other person, use it for 
any purpose, or store or copy the information in any medium. Thank you.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[alex23]

On Mar 1, 4:28 am, Rick Johnson  wrote:
> And by the way Alex, you are free to put *your* face into the conversation 
> anytime you like.

You're such a little fascist.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Chris Angelico]

On Fri, Mar 1, 2013 at 5:28 AM, Rick Johnson
 wrote:
> Q: Do you feel that the bug tracker should be a place where users discuss 
> grievances that distract volunteers from fixing actual bugs?

So you admit that discussion of your whining about perceived
grievances would distract busy people from doing useful things to and
with Python... and yet you demand GvR's *personal* involvement. I
think you grossly misunderstand the position of BDFL. It's "servant to
all", but not "grovelling, boot-licking sap with no life who spends
all day dealing with idiots". A subtle difference, I'm sure, and I can
understand how someone of your intellect could fail to recognize it.

ChrisA
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Rick Johnson]

On Wednesday, February 27, 2013 11:57:05 PM UTC-6, alex23 wrote:
> On Feb 28, 2:53 pm, Rick Johnson  wrote:
> > On Wednesday, February 27, 2013 10:18:46 PM UTC-6, alex23 wrote:
> [...]
> * Do you care about the evolution of Python or just give
> it lip service?
> 
> I don't see any problems with how Python is developing now. Then
> again, I am pretty busy using it to write code.

So go write your code and stop trying to stymie the attempts of others who wish 
to improve Python. Your participation is NOT compulsory!

> * Do you have an ideas for the name of a Python grievance
> list?
>
> http://bugs.python.org/

Well thanks for actually answering a question directly, but we must dig deeper. 
Deciding the _name_ of a list is just one small detail, the most important 
question is this:

Q: Do you feel that the bug tracker should be a place where users discuss 
grievances that distract volunteers from fixing actual bugs?

I'm of the opinion that such discussions are more suited for an entry-level 
grievance list (such as: PyWarts).

> * What are your opinions of the state of both Tkinter and
> IDLE? Are you proud of these modules/packages?
>
> I don't use them, 

So again, why bother to stymie the attempts of others who DO use them? Crawl 
back under your rock and write some code.

> ...nor do I need to feel "pride" about any part of the
> Python standard library. Either something is useful to me or not.

That's a fairly selfish outlook Alex. 

Okay, maybe you don't care about the state of Python's stdlib, fine, but other 
people do. How does flinging poo on these people help anyone? But more 
importantly how does flinging poo reflect on your image in this community?

> > * Why do you support Guido's continued reign of silence?
>
> Why do you inject hyperbole into everything you write?

The question is quite valid and your are diverting again!

> > * But most importantly, do you not want the community/
> > language to evolve or remain static?
>
> I already answered that above. [...] Can you provide a link to
> your "improved" tkinter package on PyPI? 

No, because my "awesome re-write of Tkinter" does not live at PyPI.

> Where is your draft PEP for its inclusion in the standard
> library?

I have not written a PEP on the subject. Are you suggesting that if i don't 
write a PEP my proposal is "dead in the water"? If so, this is exactly the kind 
of barriers that keep Python's stdlib in such a atrocious state!

What if i'm a horrible writer and a genius code artist? If the community judges 
the value of "source code" based on the rhetoric of a "document describing the 
source code", then they are basing their judgments on folly. What happens if i 
am a seasoned programmer but English is my second language? 

It is my opinion that PEP are great, but they should not be compulsory to 
having your ideas seriously considered by the community. A great idea is a 
great idea, no matter how much fluff you add to it. Likewise, a poor idea is a 
poor idea, and no amount of fluff could ever make it better. In this sense, PEP 
are a waste of valuable time.

And let's not forget the irony here; the default reply for documentation issues 
is for the user to "read the effing source!". Hmm, so *you* and others feel 
that reading source is compulsory for those *without* the ability to comprehend 
the source, and a waste of time for those *with* the ability to read source? Is 
this not the definition of hipocracy Alex? I have a feeling there is a bit of 
malevolence in there also.

Alex, your in ability to understand the asinine barriers a contributor to this 
community must negotiate is leading me to believe you have _insidious_ 
intentions.

> How is RickPython proceeding?

My personal Python fork is of no concern to this community, or this mailing 
list; STAY ON TOPIC!

> > What is your opinion on anything "Python related" Alex?
> My biggest regret re Python is that you found it more
> appealing than Ruby and we got saddled with you instead.

Ahh, and this little "off-hand" statement uncovers the hidden truth. Regardless 
of your personal feeling of me, your underlying hatred of Python is *glaringly* 
apparent!

> You responded to a request for advice on learning how to
> handle complex projects with:
> 
> "Before you decide to start participating in outside projects may we
> have a list of some of the software you've written for yourself? (With
> all due respect) I very seriously doubt that someone with only a "few
> months" of programming experience is ready for the real world."

The OP of that thread asked for advice on "large projects" that we might 
recommend. I tend to prefer giving people good advice and only guessing when i 
have not other choice. In order to offer good advice i need to know first how 
experienced the OP is with programming (not only python, but all languages). 

The only "hint" the OP offered was this:


#  Quote  

Re: Do you feel bad because of the Python docs?

[Chris Angelico]

On Thu, Feb 28, 2013 at 4:57 PM, alex23  wrote:
> My biggest regret re Python is that [Ranting Rick] found it more
> appealing than Ruby and we got saddled with [him] instead.

Having used Ruby a little this past couple of weeks (trying to install
a Rails application), I fully understand Rick's preference for Python;
it just proves that he wants to use a language that's actually ready
to use.

In discussion with my brother about the problems I'd been having with
Ruby, he summed up the status in one pithy phrase: Critical lack of
polish. Setting up Ruby + Rails + Spree + all the other gems that
those three require, instead of being a fairly simple half-hour job,
took me over a day.

The main issue is that Ruby functions like a niche language, but is
trying to be mainstream. Installing a gem requires that code be
compiled, and sometimes that code doesn't compile and I need to fetch
some development libraries. That's something I'm quite capable of, as
a Linux-based developer, but it's not a job for a systems
administrator. How are Ruby-based sites supposed to be deployed?

Additionally, there are a number of critical-yet-minor problems. The
standard way to invoke Rails is 'rails server' which invokes WEBrick
on port 3000. You can change that port, but to use one <=1024, you
have to be root... and there's no way to have it drop privileges
afterwards. So a Ruby on Rails system, accessible on port 80, will
have to run everything as root. No thanks. Alternatively, you can set
up firewall rules to redirect port 80 to port 3000... or have an
Apache load-balancing proxy... or, my personal favorite, set up an SSH
tunnel to localhost. All this because there's no standard way to drop
privileges after binding (nor a standard way to accept a socket passed
from another process, and listen on that - which is possible with
Ruby, just not conventional).

So, yeah. We're stuck with Rick because we have the better language+library.

ChrisA
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[alex23]

On Feb 28, 2:53 pm, Rick Johnson  wrote:
> On Wednesday, February 27, 2013 10:18:46 PM UTC-6, alex23 wrote:
> > You claim that no one has time to write a bug report. I point out that
> > if they can spend the time ranting about the bug, then they have the
> > time.
>
> And i would like to point out that all your nay-saying and condemnations are 
> taking some valuable time also. Time that could be better spent finding new 
> ways for our "new friends" to contribute.

This is a false conclusion. Why would I spend time doing this when I
don't believe it's necessary?

> * Do you care about the evolution of Python or just give it lip service?

I don't see any problems with how Python is developing now. Then
again, I am pretty busy using it to write code.

> * Do you have an ideas for the name of a Python grievance list?

http://bugs.python.org/

> * What are your opinions of the state of both Tkinter and IDLE? Are you proud 
> of these modules/packages?

I don't use them, nor do I need to feel "pride" about any part of the
Python standard library. Either something is useful to me or not.

> * Why do you support Guido's continued reign of silence?

Why do you inject hyperbole into everything you write?

> * But most importantly, do you not want the community/language to evolve or 
> remain static?

I already answered that above. You, on the other hand, constantly
dodge any direct questions or criticisms. Can you provide a link to
your "improved" tkinter package on PyPI? Where is your draft PEP for
its inclusion in the standard library? How is RickPython proceeding?

> What is your opinion on anything "Python related" Alex?

My biggest opinion is that you're a ridiculous little blowhard that
this "community" would be better off without. My biggest regret re
Python is that you found it more appealing than Ruby and we got
saddled with you instead.

Other than that, I use it daily to *get real work done*. What do you
do with it other than use it as a soapbox for your ego?

> All i've heard from you is negativity, condemnation, and insults -- with 
> exception of your statements about the GG's interface the other day, all your 
> other posts have been nothing but lectures to myself and other concerned 
> Python uses.

And here you descend into slander. I condemn *you* because you're a
contemptible twit with delusions of grandeur. I lecture *you* because
you'e particularly slow and dim-witted. As for "other concerned Python
uses", the last few threads we've both posted in I've provided
pragmatic advice, if not explicit code samples, while you have done
your usual posturing and grandiose bulshytt. You responded to a
request for advice on learning how to handle complex projects with:

"Before you decide to start participating in outside projects may we
have a list of some of the software you've written for yourself? (With
all due respect) I very seriously doubt that someone with only a "few
months" of programming experience is ready for the real world."

And you have the audacity to claim that I'm the one lecturing other
people... Who do you think you are, the Python-participation police?
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[rurpy]

On 02/27/2013 06:05 PM, Steven D'Aprano wrote:
> On Wed, 27 Feb 2013 15:20:04 -0800, rurpy wrote:
> 
>> As JoePie91 pointed out, reference material should describe its subject
>> matter completely and accurately.  Once documentation has archived that
>> minimum bar of viability, its quality is determined by how effectively
>> it transfers that information to the reader.
> 
> Those priorities are backwards.
> 
> Badly written reference materials that are ineffective at transferring 
> information is potentially useless, no matter how complete and accurate, 
> and there's often not much you can do to make it better written other 
> than throwing it away and starting again.

Why assume "useless"?  The claim is that much of the 
current Python documentation is badly written but it 
is hardly useless.  Is it even possible to be "complete 
and accurate" and totally "useless" at the same time?

> But well-written reference material that is incomplete can be 
> incrementally added to, eventually making it complete.

And badly written documentation can be incrementally rewritten 
so I don't see your point.  If you going to start with the 
premise of docs so badly written they are *totally* "useless"
then start with an equally extreme incompleteness premise: 
there is no documentation at all (including source code if 
you want to consider that, "documentation"). 

> If anyone thinks that being complete is more important than being 
> readable, let me point out that the Python source code is a 100% complete 
> and accurate reference to the behaviour of Python. 

It may be a complete and accurate if poorly readable 
reference for those who already know Python and C well
(and Java and C#/.net if you want to cover Python generally)
but the presumed target audience of the documentation does 
not necessarily know them.

And since you're claiming that readable is more important 
than complete and accurate, ask yourself which *you* would 
prefer if you could have only one: readable but incomplete
and inaccurate docs or the poorly readable but complete and 
accurate source code?

> So we're done, yes?

How so?  You have source code that is not useful for the 
intended audience of the documentation and no documentation.

> No of course not.

Right.

Perhaps a better way to look at it than I (or you) stated 
is to consider accuracy and completeness very important 
qualities of reference documentation, as is of course the 
writing quality.

> [...]
>> Documentation is the ultimate authority for what it is *supposed* to do.
> 
> Incorrect. If that were true, then there could never be a documentation 
> bug. Documentation can be buggy, just as software can be buggy. If 
> function f() is documented as doing X, but actually does Y, which one is 
> correct? In general there is no way to tell. In practice, the ultimate 
> authority is the consensus (if any!) of the people who write the software.

Correct documentation is the ultimate authority for what 
it is supposed to do.  In context, that was in contrast
to the oft-recommended technique of seeing what the software
does without reference to the documentation.  I take your 
point that when behavior and documentation disagree, it 
may not be immediately clear which is at fault but without 
reference to the documentation you will never even 
notice the discrepancy.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Chris Angelico]

On Thu, Feb 28, 2013 at 3:59 PM, Jason Friedman  wrote:
> The lazy and workable approach is to read the module documentation,
> make a reasonable effort, follow
> http://www.catb.org/esr/faqs/smart-questions.html, and voilà.

The Force is strong with this one.

If only others would follow this lazy approach...

ChrisA
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Jason Friedman]

> Python has a nice Tutorial for beginners. It is an integral part of the doc
> set. To ignore that (and the indexes) in discussing the usability of Python
> docs by beginners is to lie. (If beginners who actually read the tutorial
> have problems with particular paragraphs, improvements can be and have been
> made.)

I never thought about the quality of the Python docs until reading
these posts.  I started with Python by reading the tutorial and
browsing the module pages and have reached some level of competency.
I suppose the module pages could stand to have more examples, but as
Chris Angelico says this list should be considered part of the
documentation, in which case the documents plus this list effectively
give me any example I am wanting.  I am very grateful to those who
have given their time writing the existing documentation, answering
questions on this list, and of course writing the language!  Python
has allowed me to be more successful at my job than the other
languages I considered.

The lazy and workable approach is to read the module documentation,
make a reasonable effort, follow
http://www.catb.org/esr/faqs/smart-questions.html, and voilà.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Rick Johnson]

On Wednesday, February 27, 2013 10:18:46 PM UTC-6, alex23 wrote:
> You claim that no one has time to write a bug report. I point out that
> if they can spend the time ranting about the bug, then they have the
> time. 

And i would like to point out that all your nay-saying and condemnations are 
taking some valuable time also. Time that could be better spent finding new 
ways for our "new friends" to contribute. 

* Do you care about the evolution of Python or just give it lip service?
* Do you have an ideas for the name of a Python grievance list?
* What are your opinions of the state of both Tkinter and IDLE? Are you proud 
of these modules/packages? 
* Why do you support Guido's continued reign of silence?
* But most importantly, do you not want the community/language to evolve or 
remain static?

What is your opinion on anything "Python related" Alex? All i've heard from you 
is negativity, condemnation, and insults -- with exception of your statements 
about the GG's interface the other day, all your other posts have been nothing 
but lectures to myself and other concerned Python uses.  
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[alex23]

On Feb 28, 1:43 pm, Rick Johnson  wrote:
> Guido can start the ball rolling 10 minutes from now, all it will
> take is for him to make a public announcement...

Can you please stop this *constant* insistence that Guido talk to
you / do what you think is important? It's pointless posturing and
empty rhetoric and we've had to put up with it for *years* now. The
man has a job and at least one side project that is clearly of far
more interest & importance to him than jumping through hoops for one
incessant whiner.

Stop being so damn arrogant and insulting.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[alex23]

On Feb 28, 12:05 pm, Rick Johnson 
wrote:
> On Wednesday, February 27, 2013 5:25:25 PM UTC-6, alex23 wrote:
> > Ranting on public forums is nothing but posturing at best, and at
> > worst an attempt to blackmail-by-shame people into doing something for
> > you. Same goes for calls for "the community" to "fix" things.
>
> What you call ranting is most times people venting frustrations
> BECAUSE they want to help, but nobody is allowing them to be a
> contributing member of the community.

You claim that no one has time to write a bug report. I point out that
if they can spend the time ranting about the bug, then they have the
time. You then proceed to try and reframe the discussion to something
else entirely.

Venting frustrations isn't contributing. If someone is confused about
how to contribute, they could just *ask*, as people _regularly_ do
here, and are always given reasonable direction how to do so.

> When someone tries to offer help, in the form of constructive criticism, and 
> then somebody snaps at them, they then loose the will to help. I myself would 
> love to contribute my "quite awesome" re-write of the Tkinter GUI library, 
> but due to the friction i've encountered on this list, i am resigned to keep 
> it to myself (at least for the time being). Which is sad because python (and 
> python programmers) could greatly benefit from a polished Tkinter.

Insisting your personal project is shoved into the standard library
isn't helping. Write a PEP. Put the code up on PyPI. There's a well-
established path for progressing code from "look what I done make!"
into something that is considered part of Python.

> Alex i can assure you, there DOES exist a very harsh attitude to outside 
> opinions within this community.

Don't extend this list's reaction to you and your particular blend of
idiocy to the general response to opinions.

> Case in point: Why should ANYBODY need to voice Python problems on various 
> blogs around the web?

The two main reasons seem to be: vanity, and an unwillingness to
listen to criticism.

> This is why i will AGAIN mention my PyWarts list (Hypothetical at this point).

"Hypothetical" sums up pretty much all of your supposed contributions
to date.

> We need an official place for the many problems of Python to be discussed in 
> a fair and open manner. A place that will be open to noobs and frequented by 
> pythonisitas (including the BDFL himself!)

Starting a new forum just fragments the discussion even further.

> 
>  Path of a Python Issue
> 
> 1. All perceived problems with python get voiced on the PyWarts list
> 2. After considerable discussion, and if we can widdle the problem down to a 
> tangible bug, then a bug gets opened on the tracker.
> 3. Hopefully the bug will be resolved and closed ASAP.

Ah, so it's your way or no way, yet again.

THERE ALREADY EXISTS A PATH FOR DEALING WITH ISSUES.

> This is a linear path of inclusion that will prompt people to participate.

Right, until someone doesn't get the response they want and they
agitate for this to happen on Stackoverflow, or IRC, or their brand
new forum they've set up. You're not the first person to want to
impose your own brand of tyranny on the process.

> You and i both know we need more people working at the tracker

No one is going to be "working at the tracker", because no one is
*paid* to do such "work". People can participate by contributing, or
they can choose not to. The latter should also STFU if they're not
willing to contribute, but this seems to be a position you're unable
or unwilling to understand.

> Neither this community nor this language can survive without a steady 
> adoption of new members.

The current process is not doing anything like the damage to the
uptake of Python that you constantly claim it is, but you do love your
hyperbole.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[llanitedave]

On Wednesday, February 27, 2013 7:43:58 PM UTC-8, Rick Johnson wrote:
> 
> Python is a great language, but we need diverse ideas to keep the cogs of 
> evolution turning. Guido can start the ball rolling 10 minutes from now, all 
> it will take is for him to make a public announcement...

Geez, dude, let the man get some sleep!
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Rick Johnson]

On Wednesday, February 27, 2013 8:44:08 PM UTC-6, Chris Angelico wrote:
> On Thu, Feb 28, 2013 at 1:05 PM, Rick Johnson wrote:
> > This is why i will AGAIN mention my PyWarts list
> > (Hypothetical at this point). We need an official place
> > for the many problems of Python to be discussed in a
> > fair and open manner. A place that will be open to noobs
> > and frequented by pythonisitas (including the BDFL
> > himself!)
> > [...]
> > 
> Go start the list. 

But with that statement you keep missing the point. We DON'T need yet another 
list on yet another corner of the web. What we DO need is a list that is local 
to the community. Are you asking me to start a pywarts usenet list? Does the 
community want it to be titled "PyWarts"? How about showing me that you are 
really interested by offering some name ideas. I am quite partial to PyWarts 
because i think the name is "catchy", but i am open to outside ideas, have at 
it!

> When you get something that's worth posting, go
> post it on the tracker. And if you post something with an actual
> patch, then maybe it'll be accepted.

Yes, that's step two. First step: discussion to find the definition of the bug, 
second step: open a bug report. Having people voicing opinions on the tracker 
is diverting the time and energy of the good people who volunteer there. We 
need to move the discussion somewhere else (PyWarts)

> Why are you demanding that busy people attend to you? You are
> effectively demanding that Guido, who has a full-time job as well as
> being head of a large project, should - without compensation - read
> and actively respond to every one of your whiny posts. 

I understand the responsibilities that Guido is tasked, and i do not expect him 
to answer frivolous questions on the list. What i DO expect is that he at 
minimum publicly support the following:

1. Guido needs to wield his power by announcing (politely) that the community 
should be more open to outside opinions and methods of solving problems. This 
is the most important step and the start of a recovery process.

2. Guido should also announce that in order to achieve this goal, we need a 
very public and very intuitive path of solving Python issues. This path starts 
at a list for sharing Python related greivances (call it PyWarts if you like) , 
which HOPEFULLY he will at least make an attempt to visit from time to time. 
This list (and this path) needs to be mentioned quite prominately on the 
python.org website (which itself needs quite a bit of polishing!)

GvR has not even shown his face on python-list list for around a decade or 
more. He only posts at "py-ideas" (that i know of). This is why the community 
is in such disarray. It is paramount that he make some public appearance and 
speak of his dreams for the future. 

 "How can GvR go and declare himself a BDFL and then sail off into the sunset 
to his little island paridise of "py-ideas" without ever giving validity to his 
people and his creation? If does not want to lead anymore, fine! Say so. If he 
does, fine! Make an announcment!"

> That is simply
> not going to happen unless he *wants to*. It's up to you to make it
> worth his while, or at least interesting. That's how things work.

All i ask is for Guido to lead. That's all.

He is the only person in this whole damn community who has the influence to 
speak and have people listen. If he will publicly endorse some "good will" 
within the community, and admit that we desperately need a streamed-lined and 
linear path for solving python's many problems, i can guarantee that we will 
see a great influx of really smart people. I myself will commit every second i 
can to help move along the evolution. 

I also wish he would speak publicly about the stale nature of Tkinter and IDLE. 
Allowing these two modules to become so outdated is really tarnishing the image 
of Python's stdlib. Whether you think the modules should be in the stdlib or 
not, is *not* the question. They are there, so we must try to improve them. 

Python is a great language, but we need diverse ideas to keep the cogs of 
evolution turning. Guido can start the ball rolling 10 minutes from now, all it 
will take is for him to make a public announcement...
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Chris Angelico]

On Thu, Feb 28, 2013 at 1:05 PM, Rick Johnson
 wrote:
> This is why i will AGAIN mention my PyWarts list (Hypothetical at this 
> point). We need an official place for the many problems of Python to be 
> discussed in a fair and open manner. A place that will be open to noobs and 
> frequented by pythonisitas (including the BDFL himself!)
>
> 
>  Path of a Python Issue
> 
> 1. All perceived problems with python get voiced on the PyWarts list
> 2. After considerable discussion, and if we can widdle the problem down to a 
> tangible bug, then a bug gets opened on the tracker.
> 3. Hopefully the bug will be resolved and closed ASAP.

Go start the list. When you get something that's worth posting, go
post it on the tracker. And if you post something with an actual
patch, then maybe it'll be accepted.

Why are you demanding that busy people attend to you? You are
effectively demanding that Guido, who has a full-time job as well as
being head of a large project, should - without compensation - read
and actively respond to every one of your whiny posts. That is simply
not going to happen unless he *wants to*. It's up to you to make it
worth his while, or at least interesting. That's how things work.

ChrisA
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[llanitedave]

I just completed my first Python app for public consumption, and I was learning 
as I was coding.  I've played on the outskirts of the language for a few years, 
but until this project I'd never really immersed myself in it.  I ended up 
being confused a lot.  So, I DO have some relevant thoughts:

1.  The Python official documentation is not great, but it's not bad either.  
Some of it seems outdated, some of it is a bit hard to parse, some of it 
assumes more background knowledge on the part of the reader than is justified.

Somebody mentioned the Django documentation.  I've looked at it a bit, and it's 
*very* nice.  I do think that the PSF could take some clues from its style and 
approach. 
But those are pretty minor gripes.  I've learned a lot from referencing the 
documentation, and its still my first go-to source when I'm stuck.

2.  The Python Community:  Jopie91 wrote "I will no doubt piss off quite a few 
people with this statement, but the community around Python is one of the most 
hostile and unhelpful communities around any programming-related topic that I 
have ever seen – and with that I am not just referring to #python on Freenode, 
but to communities with a dense population of Python developers in general. 
This point actually consists of several separate attitudes and issues."

There, I'd have to say he's very, very wrong.  When I have on occasion asked 
questions on this group I've never been flamed, and I've always had people give 
me thoughtful answers that obviously took some effort to compose.

My most recent question here concerned something that was thought to be a bug, 
but was due more to my own unfamiliarity with the material combined with what 
I'd suggest really was some ambiguity on the part of the documentation.  
Nevertheless, even with the misunderstandings, my questions were treated 
respectfully, and that's all I ask.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Terry Reedy]

On 2/27/2013 8:17 PM, ru...@yahoo.com wrote:

On 02/26/2013 11:43 AM, Terry Reedy wrote:



In which JoePie91 writes:
   ...the community around Python is one of the most hostile and
   unhelpful communities around any programming-related topic that
   I have ever seen...


To me, this is a lying troll rant worth less than most of RantingRick's
posts.


Rather making his point, aren't you?


Not at all. Over the past 15 years I have make 1000s of polite helpful 
responses to perhaps 100s of different people. Others have done much the 
same. The fact that I am hostile to and occasionally make an exception 
to not responding to lying troll rants does not at all prove his lie. 
Indeed, Joe did not post here, and I was not speaking to him. I intended 
my complete post to be overall helpful to people who do read here. If 
Joe ever does post a polite question here, I hope and expect he would 
get a polite response.


--
Terry Jan Reedy

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Roy Smith]

In article <287852cd-09ee-4768-9591-c1f31fe04...@googlegroups.com>,
 Rick Johnson  wrote:

> When someone tries to offer help, in the form of constructive criticism, and 
> then somebody snaps at them, they then loose the will to help. I myself would 
> love to contribute my "quite awesome" re-write of the Tkinter GUI library, 
> but due to the friction i've encountered on this list, i am resigned to keep 
> it to myself (at least for the time being). Which is sad because python (and 
> python programmers) could greatly benefit from a polished Tkinter.

So, put it on github (or whatever), and announce its availability.  If 
the Tkinter user community finds it valuable, they'll use it.  There's 
plenty of third party packages that are better than what's packaged with 
the core system (requests vs urllib, for example).
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Rick Johnson]

On Wednesday, February 27, 2013 5:25:25 PM UTC-6, alex23 wrote:
> Ranting on public forums is nothing but posturing at best, and at
> worst an attempt to blackmail-by-shame people into doing something for
> you. Same goes for calls for "the community" to "fix" things.

What you call ranting is most times people venting frustrations BECAUSE they 
want to help, but nobody is allowing them to be a contributing member of the 
community.

When someone tries to offer help, in the form of constructive criticism, and 
then somebody snaps at them, they then loose the will to help. I myself would 
love to contribute my "quite awesome" re-write of the Tkinter GUI library, but 
due to the friction i've encountered on this list, i am resigned to keep it to 
myself (at least for the time being). Which is sad because python (and python 
programmers) could greatly benefit from a polished Tkinter. 

Alex i can assure you, there DOES exist a very harsh attitude to outside 
opinions within this community. Case in point: Why should ANYBODY need to voice 
Python problems on various blogs around the web? I think it would be in the 
interest of the Python community to have these opinions voiced here, on the 
list, for all to discuss. 

This is why i will AGAIN mention my PyWarts list (Hypothetical at this point). 
We need an official place for the many problems of Python to be discussed in a 
fair and open manner. A place that will be open to noobs and frequented by 
pythonisitas (including the BDFL himself!)


 Path of a Python Issue

1. All perceived problems with python get voiced on the PyWarts list
2. After considerable discussion, and if we can widdle the problem down to a 
tangible bug, then a bug gets opened on the tracker.
3. Hopefully the bug will be resolved and closed ASAP.

This is a linear path of inclusion that will prompt people to participate. You 
and i both know we need more people working at the tracker, and there are many 
who want to participate, but they will never participate at the "bug tracker 
level" when they get nothing but friction at the "python-list level". We all 
need to tone down the hostility and lower the bar for those who wish to help. 
Neither this community nor this language can survive without a steady adoption 
of new members.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Mark Lawrence]

On 28/02/2013 01:17, ru...@yahoo.com wrote:

On 02/26/2013 11:43 AM, Terry Reedy wrote:

On 2/26/2013 7:54 AM, Steven D'Aprano wrote:

One week ago, "JoePie91" wrote a blog post challenging the Python
community and the state of Python documentation, titled:

"The Python documentation is bad, and you should feel bad".

http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
and-you-should-feel-bad/


In which JoePie91 writes:
   ...the community around Python is one of the most hostile and
   unhelpful communities around any programming-related topic that
   I have ever seen...


To me, this is a lying troll rant worth less than most of RantingRick's
posts.


Rather making his point, aren't you?


[...]


No.

--
Cheers.

Mark Lawrence

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Roy Smith]

In article <54967758-e84c-4b9c-a09c-10fbdbec2...@googlegroups.com>,
 Rick Johnson  wrote:

> do you /really/ expect that people have the 
> time to open an issue on the bug tracker? 

There's a certain amount of socialism involved in OSS.  "From each 
according to his ability," really is the way it works.  If your ability 
is that you've discovered that the documentation isn't as good as it 
should be, you owe the project a few minutes of your time to create a 
ticket describing the problem (and, even better, suggesting how it could 
be improved).

Looking at my bugs.python.org activity, I see I've opened 30 bugs over 
the past 9-1/2 years.  Of those, 16 were explicitly against the docs, 
and a few more were of the "I'm not sure if this is a docs bug or a code 
bug, but it doesn't do what it says it does" variety.

> Do you really think that everyone 
> who uses python even knows about the bug tracker?

Everybody?  No.  But, anybody who uses OSS should understand that any 
non-trivial project has a bug tracker.  And even if they don't know 
where it is, they should be capable of typing "python bug tracker" into 
a search engine and finding it.

> Do you really think that people will believe that their opinion is 
> worthy of placing on the bug tracker?

In my experience, it's far more likely for people to over-estimate the 
important of their own opinion than to under-estimate it :-)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[rurpy]

On 02/26/2013 11:43 AM, Terry Reedy wrote:
> On 2/26/2013 7:54 AM, Steven D'Aprano wrote:
>> One week ago, "JoePie91" wrote a blog post challenging the Python
>> community and the state of Python documentation, titled:
>>
>> "The Python documentation is bad, and you should feel bad".
>>
>> http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
>> and-you-should-feel-bad/

In which JoePie91 writes:
  ...the community around Python is one of the most hostile and
  unhelpful communities around any programming-related topic that
  I have ever seen...

> To me, this is a lying troll rant worth less than most of RantingRick's 
> posts.

Rather making his point, aren't you?

>[...]
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Steven D'Aprano]

On Wed, 27 Feb 2013 15:20:04 -0800, rurpy wrote:

> As JoePie91 pointed out, reference material should describe its subject
> matter completely and accurately.  Once documentation has archived that
> minimum bar of viability, its quality is determined by how effectively
> it transfers that information to the reader.

Those priorities are backwards.

Badly written reference materials that are ineffective at transferring 
information is potentially useless, no matter how complete and accurate, 
and there's often not much you can do to make it better written other 
than throwing it away and starting again.

But well-written reference material that is incomplete can be 
incrementally added to, eventually making it complete.

If anyone thinks that being complete is more important than being 
readable, let me point out that the Python source code is a 100% complete 
and accurate reference to the behaviour of Python. So we're done, yes?

No of course not.


[...]
> Documentation is the ultimate authority for what it is *supposed* to do.

Incorrect. If that were true, then there could never be a documentation 
bug. Documentation can be buggy, just as software can be buggy. If 
function f() is documented as doing X, but actually does Y, which one is 
correct? In general there is no way to tell. In practice, the ultimate 
authority is the consensus (if any!) of the people who write the software.



-- 
Steven
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[alex23]

On Feb 27, 1:13 pm, Rick Johnson  wrote:
> Terry (with all due respect), do you /really/ expect that people
> have the time to open an issue on the bug tracker?

If someone can write a paragraph on their blog or this list
complaining about a problem, then yes, they have the time to open an
issue on the bug tracker.

This is the price of using open source software: you give back. You
don't get to say "I don't have the time for this, *someone else* fix
it". Who do you expect to give up *their* time to solve *your* issues?

Ranting on public forums is nothing but posturing at best, and at
worst an attempt to blackmail-by-shame people into doing something for
you. Same goes for calls for "the community" to "fix" things.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[rurpy]

On 02/26/2013 05:54 AM, Steven D'Aprano wrote:
> One week ago, "JoePie91" wrote a blog post challenging the Python 
> community and the state of Python documentation, titled:
> 
> "The Python documentation is bad, and you should feel bad".
> 
> http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
> and-you-should-feel-bad/
> 
> It is valuable to contrast and compare the PHP and Python docs:

tl;dr? tb

I haven't used PHP or its documentation so I can't compare it 
to Python's.  I have used Python's documentation and can say 
I agree with many of the criticisms made by JoePie91.

One of the problems with "fixing" the Python reference docs
(by which I mean primarily the Language and Library References)
it that there is no common agreement about what a "good"
reference should be.  In the Python development community
that controls the overall structure and contents of the
Python documentation, there seems to be strong minimalist
streak.  It often seems like the documentation is the 
product of a contest to find the minimum number of words to 
describe something and still be able to defend it as correct.

Any documentation must be written with a target audience in 
mind and IMO the audience for the Python reference docs should 
be programmers familiar with one or two procedural or OO 
languages at an intermediate level.  (Obviously different 
sections of documentation can modify this.  Later documentation
will assume knowledge of basic concepts like Python objects, 
argument passing and assignment semantics and so forth that
were presented earlier, and documentation for specialized 
problem domain modules, eg an SMTP module, would assume some
knowledge of email, smtp and networking.)

As JoePie91 pointed out, reference material should describe
its subject matter completely and accurately.  Once documentation
has archived that minimum bar of viability, its quality is 
determined by how effectively it transfers that information
to the reader.  I distinguish reference from tutorial material 
in that the former is optimized for looking up information
and presenting it concisely, the latter for presenting (quite 
possibly the same) information in a linear fashion with no 
forward references and presenting it verbosely and experientially.
I distinguish a language reference from a language standard 
in that the audience for the latter are language implementors
rather than users.  I would describe a reference document for 
those already competent with Python and as a big cheat-sheet.

A frequent failing of the Python docs is just plain poor
writing.  When explaining something, start with a description
of what the something is, does, etc, in a form understandable 
by the target audience.  Is there anyone who can understand
what the very useful collections.defaultdict does without
multiple rereadings?  According to its docs, it "returns a 
new dictionary-like object."  That is underspecified -- many 
things return dictionary-like objects.  It continues "it 
overrides one method and adds one writable instance variable." 
OK, but WTF does it *do*?!  It then goes on to describe its
use which one has to understand without an overarching context
and then reason backwards to eventually figure out that it is
a dict that provides for user-specified behavior when accessed 
with a key that doesn't exist [*1]

Important quality enablers are good tables of contents, 
indexes, glossaries, cross references and examples.

Examples should be used to illustrate a textual description
and never used as a substitute for textual descriptions.

Cross references are particularly important in tying together
related material that is found in disparate doc locations.  
For example, information on Python's "+" operator is found in:
 Lang: 2.5. Operators
 Lang: 3.3.7. Emulating numeric types
 Lang: 6.5. Unary arithmetic and bitwise operations
 Lang: 6.6. Binary arithmetic operations
 Lang: 6.15. Summary (mislabeled, actually operator precedence)
 Lib: 4.4. Numeric Types
 Lib: 4.6.1. Common Sequence Operations
 Lib: 10.3. operator
and probably other places I did not think to look.
The index is not much help in tying any of these together:
 "add"  -> Lib: 2.5
 "+"-> Lib: 4.4
 "plus" -> Lang: 6.5
There are also more obscure uses that should be findable such
as in float hex strings (4.4.3. Additional Methods on Float)

Cross references to similar information can help cover for
failings in the index -- if you can find some similar function 
or concept, there is (or should be) a good chance of a cross-
reference to what you really wanted.

Good documentation will anticipate the questions a reader
will have and answer them.


Rebuttals to common responses to criticism of Python docs:

Python docs are already good
* Criticisms of Python's docs pop up on the Python 
 maillist and blogs with regularity.
* Many people confuse "usable", "i've learned to use
 despite", "look impressive", etc with "good".

Google / blogs / stackoverf

Re: Do you feel bad because of the Python docs?

[Rick Johnson]

On Wednesday, February 27, 2013 7:22:44 AM UTC-6, Antoine Pitrou wrote:
> Which means that in the end you would really want a diversity of HOWTOs
> targeted at different usages of the stdlib. But it is a lot of work to
> write *and* maintain.

So instead we maintain a "simple", albeit broken, doc that experienced 
pythonista's  prefer to read, whilst newbies loath? Is not the *target* 
audience noobs?

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Mitya Sirenef]

On 02/27/2013 08:22 AM, Antoine Pitrou wrote:

Mitya Sirenef  lightbird.net> writes:

>> I think the issue with python documentation is that it ignores the 95/5
>> rule: 95% of people who land on a module's page are only looking for 5%
>> of its information.
>
> The 95/5 rule is generally a fallacy which ignores that the 5% which the
> readers are expecting to learn about is not the same 5% from reader 
to reader.

> (*)
>
> Which means that in the end you would really want a diversity of HOWTOs
> targeted at different usages of the stdlib. But it is a lot of work to
> write *and* maintain.
>
> (*) cf. http://www.joelonsoftware.com/items/2006/12/09.html
>
> Regards
>
> Antoine.
>
>

It would be absurd on my part to claim that they're precisely the same
5%. But then again, they don't have to be. Consider that some topics are
covered in the official tutorial while others are omitted -- the authors
of the tutorial were following the same rough 95/5 concept and the idea
that some readers will find stuff they don't need in the tutorial while
at the same time not finding some of what they DO need -- did not stop
them from writing the tutorial, nor does it mean the tutorial is not
useful. -m



--
Lark's Tongue Guide to Python: http://lightbird.net/larks/

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Antoine Pitrou]

Mitya Sirenef  lightbird.net> writes:
> I think the issue with python documentation is that it ignores the 95/5
> rule: 95% of people who land on a module's page are only looking for 5%
> of its information.

The 95/5 rule is generally a fallacy which ignores that the 5% which the
readers are expecting to learn about is not the same 5% from reader to reader.
(*)

Which means that in the end you would really want a diversity of HOWTOs
targeted at different usages of the stdlib. But it is a lot of work to
write *and* maintain.

(*) cf. http://www.joelonsoftware.com/items/2006/12/09.html

Regards

Antoine.


-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Antoine Pitrou]

Steven D'Aprano  pearwood.info> writes:
> 
> It is valuable to contrast and compare the PHP and Python docs:
> 
> http://php.net/manual/en/index.php
> http://www.python.org/doc/

I suppose you should compare it with http://docs.python.org/3/ instead.

> There's no doubt that one of PHP's strengths, perhaps its biggest 
> strength, is the good state of documentation.

My (probably outdated) experience with the PHP docs is that they are very
succinct and don't document failure cases or behavioral details at all.
Sure, if you only care about the big picture, they are good enough.

Regards

Antoine.


-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Mark Lawrence]

On 26/02/2013 12:54, Steven D'Aprano wrote:

One week ago, "JoePie91" wrote a blog post challenging the Python
community and the state of Python documentation, titled:

"The Python documentation is bad, and you should feel bad".

http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
and-you-should-feel-bad/

It is valuable to contrast and compare the PHP and Python docs:

http://php.net/manual/en/index.php
http://www.python.org/doc/

There's no doubt that one of PHP's strengths, perhaps its biggest
strength, is the good state of documentation. But should we feel bad
about Python's docs? I don't think that either the Python documentation
or community is as bad as JoePie91 suggests. (Well, I won't speak for the
people on Freenode's #python. It took me approximately three minutes to
be banned from there, with no warning or explanation.)

Another response to the blog post, by one of the core developers:

http://blog.briancurtin.com/posts/why-i-dont-feel-so-bad.html



Not really when we've got world leading experts to help us out 
http://xahlee.info/perl-python/python_doc.html :) * sys.maxint


--
Cheers.

Mark Lawrence

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Mitya Sirenef]

On 02/26/2013 10:09 PM, Mitya Sirenef wrote:

(As a side note, I think it  would be better if sections in datetime were

> in separate pages, it would be easier to google and the navbar on the
> left side is very crowded and rather hard to read - often I find myself
> missing stuff that's in there and ending up just scrolling down through
> the document until I find what I need -- it might be better if section
> numbers were not included there, font for keywords was not fixed width
> font, and topics didn't wrap so much - in case of datetime, all of the
> topics have enough horizontal space not to wrap and yet 3 out of 7 do 
wrap!)


In regard to Python doc topic menu readability -- compare to the django
topic menu:

https://docs.djangoproject.com/en/dev/topics/db/queries/

It's ridiculous how much more readable it is, at least to my eyes!

 -m


--
Lark's Tongue Guide to Python: http://lightbird.net/larks/

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Rick Johnson]

On Tuesday, February 26, 2013 7:48:51 PM UTC-6, Terry Reedy wrote:
> On 2/26/2013 1:52 PM, Devin Jeanpierre wrote:
> > 
> > [...snip legit complaint...]
> > 
> Have you opened an issue, or checked for existing issue? I would be open 
> to the idea that entries like that for int should not be overly type 
> specific and imply that the defaults are the only possibilities.

Terry (with all due respect), do you /really/ expect that people have the time 
to open an issue on the bug tracker? Do you really think that everyone who uses 
python even knows about the bug tracker? Do you really think that people will 
believe that their opinion is worthy of placing on the bug tracker? Do you 
really?

I think most will just end up ignoring the docs and either be forced to give up 
on Python or look for documentation elsewhere. Now, you could react to that 
truth by saying:

 "Well, who cares! The docs are the docs and if people can't grok them then too 
bad for them because i think they are awesome."

Sadly (in actuality) it's too bad for *you* Terry (along with the many other 
people who maintain docs) when you ignore the many request for changes. 
Remember, if people just ignore the docs because of these abominations you and 
everyone else are basically wasting your time maintaining the docs! Do you 
understand this fact?

Terry Implies: "We will write the docs how *we* see fit, and to hell with your 
feeble misunderstandings. You are beneath us! *We* are the anointed ones. *We* 
know everything!"
 
Look i know your intentions are noble, and yes my wording was a bit 
theatrically unfair, but this is /exactly/ how people are interpreting your 
intentions Terry. Please don't become a zealot. Python will never be perfect! I 
can assure you.

And besides, is a bug tracker /really/ the place to voice the many legitimate 
problems concerning python's documentation or stdlib? Forgive me, but I thought 
bug trackers where for tracking ,umm... well, BUGS! 

This is why i mentioned the need for an official "PyWarts" (group or list) so 
these folks will have a platform to voice their frustrations. A very PUBLIC and 
very ACCESSIBLE and very WELL KNOWN platform. Because if IS NOT all three of 
these things, then it IS nothing.

But you cannot just hand them a microphone and then stick your fingers in your 
ears. You need to /listen/ carefully and try to place yourself into their 
shoes. I can assure you that the Python docs, and the language itself, could 
use some polishing. Stop taking these complaints personally and start listening 
with an objective ear; please?
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Mitya Sirenef]

Subject:   Re: Do you feel bad because of the Python docs?  To:
python-list@python.org Cc:Bcc:
-=-=-=-=-=-=-=-=-=# Don't remove this line #=-=-=-=-=-=-=-=-=- On
 02/26/2013 09:00 PM, Terry Reedy wrote:

On 2/26/2013 1:58 PM, Mitya  Sirenef wrote:

>
>> I think the issue with python documentation is that it ignores the
>> 95/5 rule: 95% of people who land on a module's page are only looking
>> for 5% of its information. So ideally it'd be separated in two
>> different pages or two sections of the same page, something like:
>>
>> 
===

>>
>>
>> Hi, chances are you are the 95% of people who isn't interested in the
>> intricacies, obscure edge cases et cetera. Here are the few common
>> use cases for this module:
>>
>> ...
>>
>> ...
>>
>> ...
>>
>> 
===

>>
>>
>> Hi, the section above obviously did not suit your needs, so you must
>> be in the 5% who has no choice but to either read through or at least
>> glance through, or use search, to find what you need in the following
>> umpteen million of screenfuls:
>>
>> ... * 100
>>
>>
>> 
===

>>
>>
>> Why doesn't Python do that?
>
> We are not literally going to write text like that, but we did
> recently re-organized the doc for one module specifically to put the
> most commonly used stuff (about the 'convenience' functions) at the
> top instead of buried where it was.


Yes, I didn't mean it would be literally worded like that :-).





>> Quite simply, it's a lot more work: you have to separate most useful
>> parts from the rest, which involves judgement calls and will cause
>> some disagreement and ultimately won't be perfect. Once done, two
>> separate sections need to be mainained and kept in sync.
>
> In the case above, there is no duplication to be kept in sync. More
> the problem is that people working of the docs tend to either leave or
> move on to code. Report like 'This section is unclear' are not too
> helpful either.
>


I don't think that would work in the general case, for all modules,
because the 'inclusive' section should not be missing items that
logically belong there. For example, if I'm looking through string
formatting subsection, it would be confusing if some items were missing
because they were moved to the top together with other items from
different subsections.

In addition, the 'inclusive' section would have some advanced notes that
would not be included in the first section, even if items themselves may
be there.


For example, let's take timedelta section:

http://docs.python.org/2/library/datetime.html#timedelta-objects


At the end of this section there is a dozen lines of helpful examples.

I think vast majority of visitors need these examples (not a complete
list, just an example of examples), and it would be ideal if they were
shown at the very top of the page, without the need to scroll down:



from datetime import  timedelta, datetime

>>> three_days = timedelta(days=3)
>>> datetime.now()
datetime.datetime(2013, 2, 26, 21, 45, 44, 371334)

datetime.now() +  three_days

datetime.datetime(2013, 3, 1, 21, 45, 34, 427403)

old_date =  datetime(2013, 2, 10)

>>> if datetime.now() - old_date > timedelta(days=10):
...  print("It's been more than 10 days since %s" % old_date)
It's been more than 10 days since 2013-02-10 00:00:00

year =  timedelta(weeks=40, days=84, hours=23,

...  minutes=50, seconds=600)  # adds up to 365 days

year.total_seconds()

31536000.0


(As a side note, I think it would be better if sections in datetime were
in separate pages, it would be easier to google and the navbar on the
left side is very crowded and rather hard to read - often I find myself
missing stuff that's in there and ending up just scrolling down through
the document until I find what I need -- it might be better if section
numbers were not included there, font for keywords was not fixed width
font, and topics didn't wrap so much - in case of datetime, all of the
topics have enough horizontal space not to wrap and yet 3 out of 7 do wrap!)


Of course, it can be argued that these are minor issues, that relevant
parts of documentation are still quite easy to get to, and if it takes a
few minutes longer, it's not the end of the world.

In my view, such small matters are more important than it looks, because
working on a proj

Re: Do you feel bad because of the Python docs?

[Steven D'Aprano]

On Tue, 26 Feb 2013 17:48:27 +, MRAB wrote:

> On 2013-02-26 14:26, Chris Angelico wrote:
>> On Wed, Feb 27, 2013 at 12:56 AM, Roy Smith  wrote:
>>> When people ask PHP questions, the questions tend to be phrased as
>>> "what do I type to get X", and the answers come back that way too. 
>>> The forums are full of, "I had the same problem.  Somebody told me to
>>> do this.  I don't really understand it, but it worked for me and maybe
>>> it'll work for you too".
>>
>> A problem that's majorly exacerbated by the myriad ways of doing some
>> things, with some of those ways deprecated and others theoretically
>> plausible but hopelessly impractical.
>>
>> Here's an actual example that came up today at work. Suppose you have a
>> user-provided string that's supposed to contain a URL, and you need to
>> ensure that it doesn't have a trailing slash, so you can later add
>> "/foo" or "/bar". (Or alternatively, ensure that it DOES have a
>> trailing slash. Either works.) Start the timer, go find out how to do
>> it. Assume you are broadly familiar with PHP, and know how to do the
>> basics of string handling, and are competent at searching the web.
>> Ready? Go!
>>
>> I'll wait for you to come back.
>>
>> ... Okay, some of you are back now. Just giving the stragglers time to
>> finish losing their marbles...
>>
>> Alright. Here's what I found in a recreation of today's search. Google
>> search: php last character of string
>>
>> http://php.net/manual/en/function.substr.php -- okay, so I can use
>> substr, but not string indexing, to find out what the last character is
>> -- "Returns the extracted part of string; or FALSE on failure, or an
>> empty string." What kind of failures result in FALSE, and what kind in
>> an empty string?
>>
> [snip]
> The page http://php.net/manual/en/function.substr.php says:
> 
>  Description
>  string substr ( string $string , int $start [, int $length ] )
> 
> OK. It then goes on to say:
> 
>  Parameters
>  string
>  The input string. Must be one character or longer.
> 
> What? The input string can't be an empty string?

Huh, this is PHP. You're lucky it doesn't say:

"The input string. Must be one character or longer, except for the case-
insensitive string 'something-magical-happens-here'."

*wink*


-- 
Steven
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Terry Reedy]

On 2/26/2013 1:58 PM, Mitya Sirenef wrote:


I think the issue with python documentation is that it ignores the 95/5
rule: 95% of people who land on a module's page are only looking for 5%
of its information. So ideally it'd be separated in two different pages
or two sections of the same page, something like:

===


Hi, chances are you are the 95% of people who isn't interested in the
intricacies, obscure edge cases et cetera. Here are the few common use
cases for this module:

...

...

...

===


Hi, the section above obviously did not suit your needs, so you must be
in the 5% who has no choice but to either read through or at least
glance through, or use search, to find what you need in the following
umpteen million of screenfuls:

... * 100


===


Why doesn't Python do that?


We are not literally going to write text like that, but we did recently 
re-organized the doc for one module specifically to put the most 
commonly used stuff (about the 'convenience' functions) at the top 
instead of buried where it was.



Quite simply, it's a lot more work: you have
to separate most useful parts from the rest, which involves judgement
calls and will cause some disagreement and ultimately won't be perfect.
Once done, two separate sections need to be mainained and kept in sync.


In the case above, there is no duplication to be kept in sync. More the 
problem is that people working of the docs tend to either leave or move 
on to code. Report like 'This section is unclear' are not too helpful 
either.


--
Terry Jan Reedy

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Terry Reedy]

On 2/26/2013 1:52 PM, Devin Jeanpierre wrote:


I would assert it isn't very kind to those even with basic fundamentals.

For example, under precisely what circumstances does int() raise
TypeError? You won't find that under either int's documentation, or
TypeError's documentation, you have to look it up under __int__, which
is _not_ a basic fundamental. And rather than helping you along the
way, the documentation for int() actively misleads you by its
implicature that the only acceptable types are strings, ints, and
floats. And then even if you have the foresight to remember "oh yeah,
isn't there a special method for this?", you have to find the
documentation for __int__, which is itself is three quarters of the
way down this massive page:
http://docs.python.org/2/reference/datamodel.html


Have you opened an issue, or checked for existing issue? I would be open 
to the idea that entries like that for int should not be overly type 
specific and imply that the defaults are the only possibilities.
Perhaps there should be a cross-reference to corresponding special 
methods. Perhaps that idea might be opposed. I am not sure. Perhaps 
Built-in Functions needs a bit more general explanatory text at the top.


--
Terry Jan Reedy

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Jerome Covington]

Hi I'm a Python enthusiast who originally found the Python docs at
python.org to be one of the main reasons that my enthusiasm was fed. Also
the thoughtful presence of docstrings throughout good projects and
libraries gives me the feeling that finding out how to do something in
Python is just as easy as finding out how to do something else in PHP.

-- 
Regards,
Jerome
Music  || Web
Dev
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Chris Angelico]

On Wed, Feb 27, 2013 at 12:15 PM, Mark Janssen
 wrote:
> On Tue, Feb 26, 2013 at 4:54 AM, Steven D'Aprano
>  wrote:
>>
>> There's no doubt that one of PHP's strengths, perhaps its biggest
>> strength, is the good state of documentation. But should we feel bad
>> about Python's docs?
>
> I don't think so at all.  I think the python docs are quite well organized.
> Who googles for python knowledge when you can just go to the official site
> and use the doc search?

I'm not sure if you're trolling or not... The python.org search is one
of its weakest attributes; on the main http://python.org/ search, it's
now been replaced by a Google site-search, but the box on the side in
http://docs.python.org/ still gives the annoyingly slow internal
search. So no, I don't go to the official site search, I use Google
(with or without site:python.org to restrict the results - most often
without).

ChrisA
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Rick Johnson]

On Tuesday, February 26, 2013 4:17:22 PM UTC-6, Jason Swails wrote:
> Just to throw in my 2c -- in the same way that 'a picture
> is worth a thousand words', an interactive interpreter is
> worth volumes of documentation (especially one with such a
> nice help()/__doc__ functionality).

Yes! I don't even know why people care about the Python docs anyway. One of the 
most under-appreciated (and maybe even unknown) aspects of the Python language 
is the power of doc strings and the help function. Not to mention the awesome 
introspection capabilities via a few built-in functions:

id(obj)
isinstance(obj, type)
issubclass(obj, klass)
repr(obj)
type(obj)
bool(obj)
dir(obj)
...


As for the docs: 

I would say that if you are searching for a "particular something" (and the 
help function has failed you), then skip the docs and use Google instead. The 
docs only seem to work well when read in a "linear" fashion; with exception of 
the "global module index" and the "language reference" sections.

As for the "official tutorial", do yourself a favor and DON'T read it (or never 
read it) until AFTER you are comfortable with python. It's not so much that the 
tutorial is lacking, it's more that the tutorial uses poor example code and as 
such is an abomination. That's my opinion anyway. There are tons of great 
python tutorials on the web.

> You aren't sure what errors are thrown by a particular
> function?  Fire up an interpreter and feed the function
> junk.  You'll get your answer faster than you can Google,
> and often learn neat stuff along the way. 

Yes! Interactive sessions are what make python so damn great! If you don't have 
an editor window and a shell window open when writing (python) code, you are 
doing something wrong.

> (I recall one of
> RR's posts that actually had some good tips to learn-via-
> interpreter).

I don't remember the exact thread off-hand, but i must admit you can find loads 
of great information in my threads! :-P
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Mark Janssen]

On Tue, Feb 26, 2013 at 4:54 AM, Steven D'Aprano <
steve+comp.lang.pyt...@pearwood.info> wrote:

> There's no doubt that one of PHP's strengths, perhaps its biggest
> strength, is the good state of documentation. But should we feel bad
> about Python's docs?


I don't think so at all.  I think the python docs are quite well organized.
 Who googles for python knowledge when you can just go to the official site
and use the doc search?

Mark
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[emile]

On 02/26/2013 11:00 AM, nn wrote:

> What it could have is better searching capability and a way to see
> more examples. Examples would clutter the documentation so maybe they
> should be collapsible, but you can never have enough examples.

A good resource (although only covering up to v2.3) is effbot's guide to 
the standard library available at


  http://effbot.org/zone/librarybook-index.htm

It's pretty much _all_ examples.

Emile



--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Jason Swails]

Just to throw in my 2c -- in the same way that 'a picture is worth a
thousand words', an interactive interpreter is worth volumes of
documentation (especially one with such a nice help()/__doc__
functionality).  It's worth pointing out that 'interpreter' appears in the
original rant once (according to ctrl-F, whole thing was tl;dr):

Want to know how the Python interpreter deals with input Y? Read the
source. And so on, and so on.

Not: "Open up an interpreter and input Y"

You aren't sure what errors are thrown by a particular function?  Fire up
an interpreter and feed the function junk.  You'll get your answer faster
than you can Google, and often learn neat stuff along the way. (I recall
one of RR's posts that actually had some good tips to
learn-via-interpreter).

Also, I'll bet the way I learned Python effectively would seem like
nails-on-a-chalkboard to others -- and vice versa.  The 'one-size-fits-all'
doesn't work for documentation.  Complete and concise often battle, with no
clear winner.

And his representation of the Python community does not appear to be
representative of my experience (threads begun via trolling rants
notwithstanding).  But he's ranting on his blog; not a big deal really.

--Jason
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Rotwang]

On 26/02/2013 12:54, Steven D'Aprano wrote:

One week ago, "JoePie91" wrote a blog post challenging the Python
community and the state of Python documentation, titled:

"The Python documentation is bad, and you should feel bad".

http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
and-you-should-feel-bad/

It is valuable to contrast and compare the PHP and Python docs:

http://php.net/manual/en/index.php
http://www.python.org/doc/

There's no doubt that one of PHP's strengths, perhaps its biggest
strength, is the good state of documentation. But should we feel bad
about Python's docs?


I strongly disagree with most of what the author writes. To start with, 
there's this:


  Let’s start out with a simple example. Say you are a developer that
  just started using PHP, and you want to know how to get the current
  length of an array. You fire up a browser and Google for “PHP array
  length site:php.net”. The first result is spot-on, and one minute
  later, you know that count($arr) will suffice.

  Now let’s say that you wish to do the same in Python. In this case,
  you would Google for “Python list length site:docs.python.org”, and
  the first result is… a page with several chapters on standard types?

It seems to me that this is /completely/ the wrong way for a developer 
who's new to Python to go about learning the language. If you don't know 
enough Python to be familiar with len(), the sensible thing to is not to 
try coding by finding out individual language features as and when you 
need them, but to read the tutorial, systematically from start to 
finish. This list is continually being bombarded with questions from 
people who tried the former only to become stuck when something didn't 
work the way they thought it should (I've been guilty of this too), 
because knowing vocabulary is not the same thing as knowing how a 
language works. The majority of such questions could have been answered 
by simply reading the tutorial. More still could be answered by reading 
the language reference, which really isn't very long.


That's not to say that experienced users don't need to look things up, 
but then why would one restrict a web search to docs.python.org? Almost 
every question I've had about how to do something in Python has already 
been asked at StackExchange, and Google will find it.


  When you Google for something, you will end up on a page that
  explains a lot of things, including what you’re looking for. But how
  are you supposed to know where on the page it is, or whether it’s
  even on the page at all? The problem here is that the particular
  operation you are trying to find documentation on, does not have its
  own page.

And the solution is Ctrl-f.

  The general norm for the Python community appears to be that if you
  are not already familiar with the language, you do not deserve help.
  If you do something in a less-than-optimal way, other Python
  developers will shout about how horrible you are without bothering to
  explain much about what you did wrong. When you ask out of curiosity
  how a certain thing works, and that thing is considered a bad
  practice, you will get flamed like there’s no tomorrow – even if you
  had no intention of ever implementing it.

This is not my experience at all. Even when asking questions that I 
could have answered myself if I had RTFM, I've received helpful advice 
and nothing that could be construed as a flame. I don't know how this 
compares to other programming language communities, but it's much 
friendlier to newcomers here than, say, sci.math (whose competent 
regulars are understandably suspicious of people asking idiotic 
questions, given how many of those people turn out to be cranks).


  PHP solves [ambiguity] by having examples for every single function
  and class. If you’re not sure what is meant with a certain sentence in
  the description, you just look at one of the included examples, and
  all ambiguity is removed. It’s immediately obvious how to use things.

Python solves this by having an interactive interpreter. The tutorial 
goes to the trouble of pointing out that "[i]t helps to have a Python 
interpreter handy for hands-on experience".


  If you are an experienced developer, then you are most likely in a
  very bad position to judge how beginner-friendly the documentation
  for a language is.

  [...]

  Most of all, accept that your personal experiences with Python, as an
  experienced developer, are not worth very much. Listen to the newbies
  when they tell you the documentation is hard to read or find stuff in.

But I'm not an experienced developer. I'm an amateur hobbyist who came 
to learn Python having only had any real programming experience with BBC 
BASIC and OPL (both as a child). I read the tutorial, then I read the 
language reference, now I'm reading the library reference. They're all fine.



--
I have made a thing that superficially resembles music:

http://soundcloud.com/eroneity/we

Re: Do you feel bad because of the Python docs?

[nn]

On Feb 26, 11:19 am, notbob  wrote:
> On 2013-02-26, Steven D'Aprano  wrote:
>
> > "The Python documentation is bad, and you should feel bad".
>
> Ahh!  A point at which I can interject.
>
> As a rank green python noob, I definitely hava an opinion on python
> documentation and it's not entirely flattering.  OTOH, it's hard to
> toss any other single linux based documentation up as a sterling
> example.  IOW, I've seen worse.  How am I learning about python?
>
> Several sources.  The "Non-Programmer's Tutorial" docs from wikibooks
> was a false start.  It goes for about 2 pages before I realized
> they've snuck in some python syntax without explaining it.  So, I jump
> over to "The Python Tutorial", which immediately leaves me submerged,
> as it's waaay over my clueless head.  I flounder around and
> desperately grab onto "Basic Python" over at About.com.  Finally, I'm
> rescued!
>
> Whoda thunk it?  I usta despise About.com.  But, they've matured
> greatly since their early days.  I'm not a programmer.  In fact I
> really dislike programming.  But, as a long time linux user, I really
> need to learn a useful higher language.  And here is this website that
> takes me by the hand and speaks to me like what I am.  Dumb as a post
> and disinterested.  But, they are patient.  They explain basic
> programming concepts before launching into specifics.  When they do
> get specific, they use simple examples that make sense.  The don't
> toss in syntax they haven't fully explained.  Great site and the one
> I'm now using to progress.  I'm sure the other sites I've named will
> become helpful, eventually, but now I can move forward with
> confidence.
>
> Are python doc sites perfect?  No.  I've yet to come upon anything
> that clarifies why's and wherefores and the differences between the CMI
> IDLE and the GUI IDLE.  And boy, are they different!  OTOH, as I said,
> I've seen worse Linux docs.  BitchX or zsh?  What docs!?  Even the man
> pages took me a long time to figure out.  Bluefish?  Krita?
> Puh-leeze!  emacs?  It's a wonder I can use it at all.  ;)
>
> Despite all that, I'd say python documentation is better than a poke
> in the eye with a sharp stick.  I'm sure the official pages will make
> more sense to me when I understand more.  As it is, they jes toss out
> "lc-letter" like I know what they're talking about.  They explain it a
> little bit, but I still hadda wiki it to get the full story.
>
> As a person with some technical writing experience, I know how
> difficult it can be.  I had to be careful about who I was writing for,
> engineers or laymen.  It's the same with programming docs.  Writing
> tutorials about python as if I jes came from 5 yrs as a C programmer
> is not in the least bit helpful to a beginner like myself.  Sometimes,
> one jes hasta hunt for the right flavor.
>
> nb

For me on the other hand. The Python tutorial has been the most useful
tutorial I have ever used. I had experience with Basic and Pascal.
Most other tutorials go too slow for me and I loose interest. The
python one just kept going and after reading the dozen pages in a
couple of hours I had enough of an idea about the language to start
doing the things I was interested in.

The only thing that confused me at first was finding functions like
"open" or "input" and string methods. I lost a bit of time searching
in the language reference until I found out that they are in the
Library reference: I didn't think of "open" as a library. But now I
have no problem; all I need is found under Library reference in
section 2 and 4 and starting with section 6. I also use the global
module index when I already have an idea what I am looking for.

What it could have is better searching capability and a way to see
more examples. Examples would clutter the documentation so maybe they
should be collapsible, but you can never have enough examples. As
Einstein said:
“Example isn't another way to teach, it is the only way to teach”
Outside of the tutorial there are not a lot of succinct examples of
more advanced uses of the different keywords and builtins. Thankfully
for the libraries there is Python Module of the Week for people that
know about it.

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Mitya Sirenef]

On 02/26/2013 07:54 AM, Steven D'Aprano wrote:

One week ago, "JoePie91" wrote  a blog post challenging the Python

> community and the state of Python documentation, titled:
>
> "The Python documentation is bad, and you should feel bad".
>
> http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
> and-you-should-feel-bad/
>
> It is valuable to contrast and compare the PHP and Python docs:
>
> http://php.net/manual/en/index.php
> http://www.python.org/doc/
>
> There's no doubt that one of PHP's strengths, perhaps its biggest
> strength, is the good state of documentation. But should we feel bad
> about Python's docs? I don't think that either the Python documentation
> or community is as bad as JoePie91 suggests. (Well, I won't speak for 
the

> people on Freenode's #python. It took me approximately three minutes to
> be banned from there, with no warning or explanation.)
>
> Another response to the blog post, by one of the core developers:
>
> http://blog.briancurtin.com/posts/why-i-dont-feel-so-bad.html
>
>
>


I think the issue with python documentation is that it ignores the 95/5
rule: 95% of people who land on a module's page are only looking for 5%
of its information. So ideally it'd be separated in two different pages
or two sections of the same page, something like:

===

Hi, chances are you are the 95% of people who isn't interested in the
intricacies, obscure edge cases et cetera. Here are the few common use
cases for this module:

...

...

...

===

Hi, the section above obviously did not suit your needs, so you must be
in the 5% who has no choice but to either read through or at least
glance through, or use search, to find what you need in the following
umpteen million of screenfuls:

... * 100


===

Why doesn't Python do that? Quite simply, it's a lot more work: you have
to separate most useful parts from the rest, which involves judgement
calls and will cause some disagreement and ultimately won't be perfect.
Once done, two separate sections need to be mainained and kept in sync.
It's important that they don't contradict each other.

Right now places like SO and mailing list act like the first section I
described. The issue is that they're not always up to date and not
guaranteed to be correct, are not in a consistent style and depth, are
not centralized.

 -m


--
Lark's Tongue Guide to Python: http://lightbird.net/larks/

Is life not a thousand times too short for us to bore ourselves?
Friedrich Nietzsche

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Devin Jeanpierre]

On Tue, Feb 26, 2013 at 11:38 AM, Adam W.  wrote:
> I think learning a language from the documentation is an unreasonable 
> expectation and burden for the authors.

That's how I learned it. The Python tutorial, together with the stdlib
reference manual, are often recommended to beginners to Python in
order to learn it. The combination of the documentation and consulting
other programmers helped me learn the language just fine.

> Buy a book, take a class, they are designed to provide you with a path from 
> start to finish in a sensible manner, the documentation in my opinion is 
> supposed to be a reference and a refresher with an assumed level of basic 
> fundamentals.

I would assert it isn't very kind to those even with basic fundamentals.

For example, under precisely what circumstances does int() raise
TypeError? You won't find that under either int's documentation, or
TypeError's documentation, you have to look it up under __int__, which
is _not_ a basic fundamental. And rather than helping you along the
way, the documentation for int() actively misleads you by its
implicature that the only acceptable types are strings, ints, and
floats. And then even if you have the foresight to remember "oh yeah,
isn't there a special method for this?", you have to find the
documentation for __int__, which is itself is three quarters of the
way down this massive page:
http://docs.python.org/2/reference/datamodel.html .

-- Devin
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[notbob]

On 2013-02-26, Tim Chase  wrote:

> which suggests that they've been actively maintained since 1999-2000
> or so.

in various guises, dating back to the man pages.  Not all as
thorough as the latest "manual".  Perhaps I shoulda qualified usable
docs.  ;)

nb  
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Terry Reedy]

On 2/26/2013 7:54 AM, Steven D'Aprano wrote:

One week ago, "JoePie91" wrote a blog post challenging the Python
community and the state of Python documentation, titled:

"The Python documentation is bad, and you should feel bad".

http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
and-you-should-feel-bad/


To me, this is a lying troll rant worth less than most of RantingRick's 
posts.



It is valuable to contrast and compare the PHP and Python docs:

http://php.net/manual/en/index.php
http://www.python.org/doc/


The contrast has been discussed before on python-list and even pydev. To 
repeat: in my opinion, and that of most core developers, the python docs 
are superior. It is Joe's lie to equate difference of opinion with 
indifference.


Python has a nice Tutorial for beginners. It is an integral part of the 
doc set. To ignore that (and the indexes) in discussing the usability of 
Python docs by beginners is to lie. (If beginners who actually read the 
tutorial have problems with particular paragraphs, improvements can be 
and have been made.)


Examples: Once startup is explained, the rest of the tutorial is about 
half text and half example. I think that is a good balance. Anyone who 
reads the tutorial knows how to call a function. I think doubling the 
size of the Library *Reference* with trivial, repetitive examples like:


>>> len([1,2,3])
3

would be a negative for reference use*. Python has a super-duper 
interactive mode for trying things like this oneself, and that teaches 
*better* than just reading the same thing. (And if the tutorial never 
discusses len() and its generic use for all concrete collections, it 
should.)


* Anyone who disagrees can go to
http://www.lightbird.net/py-by-example/builtin-functions.html
where you can find that and other examples for builtins and about 30 
modules. Actually, I can imagine that some beginners would benefit from 
this page as an extension of the tutorial. This site may be an outcome 
of the previous discussion, which more or less ended with the fact that 
anyone who wanted to produce php-style Python docs was free to do so.


Searching: it is true that the Python docs are written for being read by 
people, rather than by search engines#. It has a hand-crafted index 
(yes, it still needs patches) that will get you most places, especially 
for anyone who has read the tutorial to get the basics. For 'length of a 
list' one can find 'len() (built-in function)' and find that 'len' 
indeed mean length and, more generally, size.


# Anyone who wants to could develop an seo-optimized python-by-function 
website that goes into exquisite details for each function on a separate 
page.


len(collection) => count
Built-in function len() allows one to find the
* length or size of a list
* length or size of a tuple
* length or size of an array
* length or size of a string
* length or size of a bytes
* length or size of a bytearray
* length or size of a memoryview
* size of a set
* size of a frozenset
* size of a dict or dictionary
* size of dict view
* size of user-defined collecton class instances

Returns 0 for empty collections. Raises TypeError for inputs that are 
not collections or that do not support len() calls, because they do not 
have a properly written .__len__ methods.


If I were involved, I would *not* junk-up such pages with random user 
posts. Anything worth being added should be incorporated into the entry 
itself.


--
Terry Jan Reedy

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Tim Chase]

On 2013-02-26 17:54, notbob wrote:
> >>  zsh?  What docs!?
> > You mean other than the gigantic user manual?
> > http://zsh.sourceforge.net/Doc/
> 
> "This document was generated by Simon Ruderich on July 24, 2012"
> 
> 'bout damn time!!  ;)

Generated...from source that has been around for ages:

http://zsh.git.sourceforge.net/git/gitweb.cgi?p=zsh/zsh;a=history;f=Doc;hb=dd3b0506f99e690f521d9bf449dea47a51502cb2;pg=11

which suggests that they've been actively maintained since 1999-2000
or so.

-tkc


-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[notbob]

On 2013-02-26, Andrew Berg  wrote:
> On 2013.02.26 10:19, notbob wrote:
>>  zsh?  What docs!?
> You mean other than the gigantic user manual?
> http://zsh.sourceforge.net/Doc/

"This document was generated by Simon Ruderich on July 24, 2012"

'bout damn time!!  ;)

nb
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[MRAB]

On 2013-02-26 14:26, Chris Angelico wrote:

On Wed, Feb 27, 2013 at 12:56 AM, Roy Smith  wrote:

When people ask PHP questions, the questions tend to be phrased as "what
do I type to get X", and the answers come back that way too.  The forums
are full of, "I had the same problem.  Somebody told me to do this.  I
don't really understand it, but it worked for me and maybe it'll work
for you too".


A problem that's majorly exacerbated by the myriad ways of doing some
things, with some of those ways deprecated and others theoretically
plausible but hopelessly impractical.

Here's an actual example that came up today at work. Suppose you have
a user-provided string that's supposed to contain a URL, and you need
to ensure that it doesn't have a trailing slash, so you can later add
"/foo" or "/bar". (Or alternatively, ensure that it DOES have a
trailing slash. Either works.) Start the timer, go find out how to do
it. Assume you are broadly familiar with PHP, and know how to do the
basics of string handling, and are competent at searching the web.
Ready? Go!

I'll wait for you to come back.

... Okay, some of you are back now. Just giving the stragglers time to
finish losing their marbles...

Alright. Here's what I found in a recreation of today's search.
Google search: php last character of string

http://php.net/manual/en/function.substr.php
-- okay, so I can use substr, but not string indexing, to find out
what the last character is
-- "Returns the extracted part of string; or FALSE on failure, or an
empty string." What kind of failures result in FALSE, and what kind in
an empty string?


[snip]
The page http://php.net/manual/en/function.substr.php says:

Description
string substr ( string $string , int $start [, int $length ] )

OK. It then goes on to say:

Parameters
string
The input string. Must be one character or longer.

What? The input string can't be an empty string?

--
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Andrew Berg]

On 2013.02.26 10:19, notbob wrote:
>  zsh?  What docs!?
You mean other than the gigantic user manual?
http://zsh.sourceforge.net/Doc/

-- 
CPython 3.3.0 | Windows NT 6.2.9200 / FreeBSD 9.1
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Adam W.]

I think learning a language from the documentation is an unreasonable 
expectation and burden for the authors.

Buy a book, take a class, they are designed to provide you with a path from 
start to finish in a sensible manner, the documentation in my opinion is 
supposed to be a reference and a refresher with an assumed level of basic 
fundamentals.

I'm currently taking a class in ARM assembly, the notion that I should expect 
to plop the thousand+ page reference manual on my desk and just "get to it" is 
absurd.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[notbob]

On 2013-02-26, Steven D'Aprano  wrote:

> "The Python documentation is bad, and you should feel bad".

Ahh!  A point at which I can interject.

As a rank green python noob, I definitely hava an opinion on python
documentation and it's not entirely flattering.  OTOH, it's hard to
toss any other single linux based documentation up as a sterling
example.  IOW, I've seen worse.  How am I learning about python?

Several sources.  The "Non-Programmer's Tutorial" docs from wikibooks
was a false start.  It goes for about 2 pages before I realized
they've snuck in some python syntax without explaining it.  So, I jump
over to "The Python Tutorial", which immediately leaves me submerged,
as it's waaay over my clueless head.  I flounder around and
desperately grab onto "Basic Python" over at About.com.  Finally, I'm
rescued!

Whoda thunk it?  I usta despise About.com.  But, they've matured
greatly since their early days.  I'm not a programmer.  In fact I
really dislike programming.  But, as a long time linux user, I really
need to learn a useful higher language.  And here is this website that
takes me by the hand and speaks to me like what I am.  Dumb as a post
and disinterested.  But, they are patient.  They explain basic
programming concepts before launching into specifics.  When they do
get specific, they use simple examples that make sense.  The don't
toss in syntax they haven't fully explained.  Great site and the one
I'm now using to progress.  I'm sure the other sites I've named will
become helpful, eventually, but now I can move forward with
confidence.

Are python doc sites perfect?  No.  I've yet to come upon anything
that clarifies why's and wherefores and the differences between the CMI
IDLE and the GUI IDLE.  And boy, are they different!  OTOH, as I said,
I've seen worse Linux docs.  BitchX or zsh?  What docs!?  Even the man
pages took me a long time to figure out.  Bluefish?  Krita?
Puh-leeze!  emacs?  It's a wonder I can use it at all.  ;)

Despite all that, I'd say python documentation is better than a poke
in the eye with a sharp stick.  I'm sure the official pages will make
more sense to me when I understand more.  As it is, they jes toss out
"lc-letter" like I know what they're talking about.  They explain it a
little bit, but I still hadda wiki it to get the full story.

As a person with some technical writing experience, I know how
difficult it can be.  I had to be careful about who I was writing for,
engineers or laymen.  It's the same with programming docs.  Writing
tutorials about python as if I jes came from 5 yrs as a C programmer
is not in the least bit helpful to a beginner like myself.  Sometimes,
one jes hasta hunt for the right flavor.  

nb

-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Steven D'Aprano]

On Wed, 27 Feb 2013 01:26:47 +1100, Chris Angelico wrote:

> And just to add to the pile of ways this could be done, the first
> response in this thread
> https://forums.digitalpoint.com/threads/how-to-get-last-character-in-
string.796134/
> suggests *reversing the string* and indexing from the front.

Oooh, deja vu! It's like it's 1988 and I'm learning to program in 
Hypertalk all over again!



-- 
Steven
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Chris Angelico]

On Wed, Feb 27, 2013 at 12:56 AM, Roy Smith  wrote:
> When people ask PHP questions, the questions tend to be phrased as "what
> do I type to get X", and the answers come back that way too.  The forums
> are full of, "I had the same problem.  Somebody told me to do this.  I
> don't really understand it, but it worked for me and maybe it'll work
> for you too".

A problem that's majorly exacerbated by the myriad ways of doing some
things, with some of those ways deprecated and others theoretically
plausible but hopelessly impractical.

Here's an actual example that came up today at work. Suppose you have
a user-provided string that's supposed to contain a URL, and you need
to ensure that it doesn't have a trailing slash, so you can later add
"/foo" or "/bar". (Or alternatively, ensure that it DOES have a
trailing slash. Either works.) Start the timer, go find out how to do
it. Assume you are broadly familiar with PHP, and know how to do the
basics of string handling, and are competent at searching the web.
Ready? Go!

I'll wait for you to come back.

... Okay, some of you are back now. Just giving the stragglers time to
finish losing their marbles...

Alright. Here's what I found in a recreation of today's search.
Google search: php last character of string

http://php.net/manual/en/function.substr.php
-- okay, so I can use substr, but not string indexing, to find out
what the last character is
-- "Returns the extracted part of string; or FALSE on failure, or an
empty string." What kind of failures result in FALSE, and what kind in
an empty string?

http://stackoverflow.com/questions/4427172/find-last-character-in-a-string-in-php
Comment on question: "There are more than 10 ways of doing this!"
The accepted answer, fortunately, is a good one. Use rtrim. Okay.
That's nice. But look at the other answers: one mentions substr (as
above, that's half the question); one suggests the unwieldy form of
indexing from the back (with an explicit strlen); one answers
altogether the wrong question (suggesting the use of basename); and
one... suggests a regular expression. Now you have two problems.

And just to add to the pile of ways this could be done, the first
response in this thread
https://forums.digitalpoint.com/threads/how-to-get-last-character-in-string.796134/
suggests *reversing the string* and indexing from the front.

Maybe you tried different search terms and got better results, I don't
know. This wasn't the only search I did in trying to find the best way
to do this, but it was the one with the most amusing results.

The original rant specifically excluded sites like Stack Overflow as
valid sources, which in a way is fair enough. But it wasn't from
php.net that I got that information.

Okay. Now I'll try it again, for Python.
Google search: python last character of string
First result:
3.1.2 Strings
docs.python.org/release/1.5.1p1/tut/strings.html
Besides numbers, Python can also manipulate strings, which can be
expressed ... word[-1] # The last character 'A' >>> word[-2] # The
last-but-one character 'p' ...

The use of code with directly connected comments means that I can read
this part of the solution right there, without even clicking the link.
Search Engine Optimization FTW.

Searching for the second part, by adding the word 'remove' to the
search, brings up more third-party sites - for PHP:
http://www.if-not-true-then-false.com/2010/php-remove-last-character-from-string/
and for Python:
https://groups.google.com/forum/?fromgroups#!topic/comp.lang.python/TIX5u3Zhikc
http://stackoverflow.com/questions/9639754/python-remove-last-char-from-string-and-return-it

In both cases, answering the question, but not from the language's own
site. Forcing the matter with a site: search brings up poor results
for both languages. Python gives me:
http://docs.python.org/release/2.6/library/string.html
but nothing about slicing. PHP: Take your pick of functions, and I
hope you already know what they do, because the snippets don't help
you choose:
substr, rtrim, chop (which, once you go to the page, reveals itself to
be an alias for rtrim), strrpos, substr_replace, strstr

I'd have to say that, in the shoot-out, both languages died on their
own merits, but stood on the merits of third-party support. Fifteen
years ago, I would have called that a critical failure; in the 90s, I
would search for information only from official sources. But these
days, forum archives and blogs are some of the best way to find what
you need - granted, Sturgeon's Law applies, but frankly that applies
to a lot of documentation too (and Google's fairly good at helping you
find the 10%).

ChrisA
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Devin Jeanpierre]

On Tue, Feb 26, 2013 at 7:54 AM, Steven D'Aprano
 wrote:
> There's no doubt that one of PHP's strengths, perhaps its biggest
> strength, is the good state of documentation. But should we feel bad
> about Python's docs? I don't think that either the Python documentation
> or community is as bad as JoePie91 suggests.

Who's we? As a user of Python I feel no responsibility for the state
of Python's documentation ;)

Do I feel like it could be improved? Sure. I've never understood why
Python doesn't document information about possible errors inside the
function documentations. Instead, you have to read the exception
documentation to find out when it might be raised, and then the exact
error conditions aren't always clearly specified at all.

My understanding from talking to members of the development team has
been that this is by design, so I've of course never submitted a
patch.

> (Well, I won't speak for the
> people on Freenode's #python. It took me approximately three minutes to
> be banned from there, with no warning or explanation.)

I'm an op in #python. If you can provide logs or a nickname I could
look into this with whoever banned you (if the ban hasn't expired
already!) However, you should appreciate that, having only been there
for three minutes, you may not have understood the expectations
#python sets on tone or subject matter. It is markedly more strict
than comp.lang.python. Also, bans aren't explained (except possibly in
the kickban message, but that's rare) unless you ask about them. It's
very easy to infer a reason from context, explanations take time (if
you explain before the ban), and PMs to a just-banned person never go
well (if you explain after the ban).


As to whether or not JoePie91's observations are correct for
#python... all the observations would apply to #python except for the
ostrich and source-reading complaints, albeit viewed through a very
negative light. I would disagree with his explanations for the reasons
for things, and his ranking of the importance of things.

IMHO the most important flaw in #python is that it's unwelcoming to
new programmers, but I can't think of a decent way to fix that.
Tutoring new programmers takes a huge amount of time. At the moment I
figure that the best we can hope to do is identify them before we
confuse the hell out of them by telling them to use classes,
generators, higher order functions, and other intermediate to advanced
topics. Unfortunately, we're not good at this. (Yet? :)


By the way, interestingly enough, JoePie91 was in #python discussing
his blog post for a bit. It was a fun conversation.

-- Devin
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Zero Piraeus]

:

On 26 February 2013 08:54, Steven D'Aprano
 wrote:
> One week ago, "JoePie91" wrote a blog post challenging the Python
> community and the state of Python documentation [...]

> [...] should we feel bad about Python's docs?

The Python docs are my first port of call when I know the module (and
maybe the function) I want to use, but can't remember exactly how it
works. For that, and for me, they're very good.

I can also usually find the section I want if I'm answering a beginner
question on Stack Overflow and want to provide an explanatory link,
but if I weren't already familiar with the docs, I think it's quite
unlikely I'd find the relevant page easily. I agree with joepie91 that
the information on fundamental stuff is poorly organised.

> I don't think that either the Python documentation
> or community is as bad as JoePie91 suggests.

I think he has a point, albeit exaggerated, regarding the community -
or at least python-list, which is the part with which I'm familiar.
This list can be a little imposing for beginners, and its habit of
veering away from the original question into an esoteric discussion of
the language, while entertaining and educational to read for *me*,
might well end up causing OP to scratch their head.

I don't think it's intended, but sometimes there's also the sense that
regulars here are trying, not entirely successfully, to hide their
impatience with simple questions. I don't hang out at python-tutor, so
maybe it's better there (in which case, maybe its existence needs to
be better advertised).

I think Stack Overflow is a little better at that, possibly because
the rep system there encourages "grinding" in the MMORPG sense, and
easy questions get a bunch of people piling on with answers almost
instantaneously.

 -[]z.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Roy Smith]

In article ,
 Chris Angelico  wrote:

> There are some issues with the Googleability of the Python docs at the
> moment. It's much easier to find the official page of PHP's docs than
> Python's. Trouble is, the official page of PHP docs is a lot less
> helpful... like he says, it's in some cases flat-out wrong. And then
> you go read the comments underneath in the hope of learning what you
> need to know... and you find a pile of junk even worse than the main
> docs, but with the occasional useful gem so you can't dismiss it out
> of hand. (But it's buried among loads of code whose primary purpose is
> to explain why there's so much bad PHP code out there.)

Having lived through a year of PHP hell, I've developed a theory about 
the PHP ecosystem (i.e. docs, forums, user community, etc) vs. the 
Python ecosystem.

When people ask PHP questions, the questions tend to be phrased as "what 
do I type to get X", and the answers come back that way too.  The forums 
are full of, "I had the same problem.  Somebody told me to do this.  I 
don't really understand it, but it worked for me and maybe it'll work 
for you too".

The Python ecosystem is much more about understanding what's actually 
happening.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Do you feel bad because of the Python docs?

[Chris Angelico]

On Tue, Feb 26, 2013 at 11:54 PM, Steven D'Aprano
 wrote:
> One week ago, "JoePie91" wrote a blog post challenging the Python
> community and the state of Python documentation, titled:
>
> "The Python documentation is bad, and you should feel bad".
>
> http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
> and-you-should-feel-bad/
>
> It is valuable to contrast and compare the PHP and Python docs:
>
> http://php.net/manual/en/index.php
> http://www.python.org/doc/

There are some issues with the Googleability of the Python docs at the
moment. It's much easier to find the official page of PHP's docs than
Python's. Trouble is, the official page of PHP docs is a lot less
helpful... like he says, it's in some cases flat-out wrong. And then
you go read the comments underneath in the hope of learning what you
need to know... and you find a pile of junk even worse than the main
docs, but with the occasional useful gem so you can't dismiss it out
of hand. (But it's buried among loads of code whose primary purpose is
to explain why there's so much bad PHP code out there.)

His "experiment" (name all the possible error conditions) is one that
I guarantee you will fail in EVERY language. Even in Java, where a
method has to declare every exception it might throw, makes an
exception (if you'll excuse the pun) for "runtime errors"... such as
division by zero. So if I write a function that takes two arguments,
divides one by the other, and adds three, then I don't need to declare
that it might bomb if you give it zero and zero. Will it be in the
docs? Unlikely.

The lack of examples is a valid concern. However, PHP isn't actually
that much better, because the prolific examples don't always help.
Examples are no panacea.

Final point: "NO-ONE IS FIXING THIS". I wonder how many docs patches
he's submitted, how many newbies he's courteously and competently
assisted.

The complaints about the community definitely do not apply to
python-list. So I'd say that's a fairly good fallback: if you can't
find what you need in the docs, and you've made a genuine effort to do
so, ask on c.l.p/p-l and you'll likely get a response within a day -
sometimes within the hour. (If Giacomo says he will respond within the
hour, he will respond... within the hour!)

tl;dr: Nothing's perfect but it ain't as bad as all tharrt.

ChrisA
-- 
http://mail.python.org/mailman/listinfo/python-list