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 <

 

[rh]

FWIW, I refer to the docs often. I keep a local copy and
serve the pages up locally

1. http://docs.python.org/2/archives/python-2.7.3-docs-html.tar.bz2
2. unroll
3. cd python-2.7.3-docs-html
4. python -c 'import SimpleHTTPServer as foo;foo.test()' 9292
5. point browser to 0:9292

I find that this works now to replace step #4:
python -m SimpleHTTPServer 9292

 

[Bob Hanson]

[...] 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 <[email protected]>
Date: Wed, 06 Mar 2013 00:56:44 +0000

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

 

[Bob Hanson]

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

[...] 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 <[email protected]>
Date: Wed, 06 Mar 2013 00:56:44 +0000

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

 

[Bob Hanson]

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

[...] 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 <[email protected]>
Date: Wed, 06 Mar 2013 00:56:44 +0000

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

 

[Mark Lawrence]

[...] 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 <[email protected]>
Date: Wed, 06 Mar 2013 00:56:44 +0000

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

 

[Steven D'Aprano]

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
<[email protected]> Date: Wed, 06 Mar 2013
00:56:44 +0000

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.

 

[rh]

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 <[email protected]>
Date: Wed, 06 Mar 2013 00:56:44 +0000

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.

Can you post to comp.python.bugs? Or (e-mail address removed)?
Who wants to sign up for yet another website?

 

[Terry Reedy]

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 (e-mail address removed) describing the bug
and where you found it. If you have a suggestion how to fix it, include
that as well.

(e-mail address removed) 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.

 

[Rick Johnson]

If you find a bug in this documentation or would like to propose an
improvement, please send an e-mail to (e-mail address removed) 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?

 

[alex23]

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_?

 

[Rick Johnson]

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 throughthe 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 inPython 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 prominentlink on python.org; because if i do start a list without all these things,i will be wasting my time.

 

[Terry Reedy]

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.

 

[Michael Ross]

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

 

[Chris Angelico]

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

 

[alex23]

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

 

[Rick Johnson]

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.

 

[Rick Johnson]

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

 

[alex23]

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.

 

[Rick Johnson]

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.