Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Do you feel bad because of the Python docs?

Reply
Thread Tools

Do you feel bad because of the Python docs?

 
 
alex23
Guest
Posts: n/a
 
      03-07-2013
On Mar 7, 10:47*am, Rick Johnson <(E-Mail Removed)> 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_?
 
Reply With Quote
 
 
 
 
Rick Johnson
Guest
Posts: n/a
 
      03-07-2013
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 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.
 
Reply With Quote
 
 
 
 
Terry Reedy
Guest
Posts: n/a
 
      03-07-2013
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 http://www.velocityreviews.com/forums/(E-Mail 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?


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

 
Reply With Quote
 
Michael Ross
Guest
Posts: n/a
 
      03-07-2013
On Thu, 07 Mar 2013 02:28:10 +0100, Chris Kaynor
<(E-Mail Removed)> 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 <(E-Mail Removed)> wrote:
>>
>>
>> On Mar 7, 10:47 am, Rick Johnson <(E-Mail Removed)> 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
>>

>

 
Reply With Quote
 
Chris Angelico
Guest
Posts: n/a
 
      03-07-2013
On Thu, Mar 7, 2013 at 12:31 PM, Rick Johnson
<(E-Mail Removed)> 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
 
Reply With Quote
 
alex23
Guest
Posts: n/a
 
      03-07-2013
On Mar 7, 11:31*am, Rick Johnson <(E-Mail Removed)> 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".
 
Reply With Quote
 
Rick Johnson
Guest
Posts: n/a
 
      03-07-2013
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.
 
Reply With Quote
 
Rick Johnson
Guest
Posts: n/a
 
      03-07-2013
On Wednesday, March 6, 2013 8:28:42 PM UTC-6, alex23 wrote:
> On Mar 7, 11:31 am, Rick Johnson <(E-Mail Removed)> 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 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.
 
Reply With Quote
 
alex23
Guest
Posts: n/a
 
      03-07-2013
On Mar 7, 12:57*pm, Rick Johnson <(E-Mail Removed)> 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.
 
Reply With Quote
 
Rick Johnson
Guest
Posts: n/a
 
      03-07-2013
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.
 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Re: Do you feel bad because of the Python docs? Jean-Michel Pichavant Python 0 03-01-2013 10:06 AM
What do you use java for ? AndDoes Java make you feel happy? zelzel.zsu@gmail.com Java 15 11-12-2005 03:54 AM
ActiveX apologetic Larry Seltzer... "Sun paid for malicious ActiveX code, and Firefox is bad, bad bad baad. please use ActiveX, it's secure and nice!" (ok, the last part is irony on my part) fernando.cassia@gmail.com Java 0 04-16-2005 10:05 PM
24 Season 3 Bad Bad Bad (Spoiler) nospam@nospam.com DVD Video 12 02-23-2005 03:28 AM
24 Season 3 Bad Bad Bad (Spoiler) nospam@nospam.com DVD Video 0 02-19-2005 01:10 AM



Advertisments