Re: Python docs disappointing - group effort to hire writers?

[Mark Lawrence]

Bill Jones wrote:

On Aug 8, 3:27 pm, Mark Lawrence  wrote:

Kee Nethery wrote:

As someone trying to learn the language I want to say that the tone on
this list towards people who are trying to learn Python  feels like it
has become anti-newbies.

[snip]


Kee Nethery

My gut feeling (which could of course be wrong) is that many hard core
Pythonistas are cheesed off with newbies who refuse to help themselves.


The funny thing is that their response is to shutdown changes that are
intended
to *help* newbies help themselves. It seems self-defeating to me.

And I still do not believe this to be true.  Documents are being changed 
all the time.  See the python-dev mailing list "Summary of python 
tracker issues" dated 17/24/31 July and 07/14 August 2009.  The only 
request I recall being rejected is someone objecting to the use of 
"weapons" in a piece of sample code.


Also see Issue6660 on the bug tracker, it is of particular interest to 
anyone who's interested in plans for python.org documentation links.


--
Kindest regards.

Mark Lawrence.

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

Re: Python docs disappointing - group effort to hire writers?

[Carl Banks]

On Aug 14, 10:15 pm, Bill Jones  wrote:
> On Aug 8, 3:27 pm, Mark Lawrence  wrote:
> > My gut feeling (which could of course be wrong) is that many hard core
> > Pythonistas are cheesed off with newbies who refuse to help themselves.
>
> The funny thing is that their response is to shutdown changes that are
> intended
> to *help* newbies help themselves. It seems self-defeating to me.

Intended to help newbies doesn't necessarily mean it actually will
help newbies.

(Just sayin'.)


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

Re: Python docs disappointing - group effort to hire writers?

[Bill Jones]

On Aug 8, 3:27 pm, Mark Lawrence  wrote:
> Kee Nethery wrote:
> > As someone trying to learn the language I want to say that the tone on
> > this list towards people who are trying to learn Python  feels like it
> > has become anti-newbies.
>
> [snip]
>
> > Kee Nethery
>
> My gut feeling (which could of course be wrong) is that many hard core
> Pythonistas are cheesed off with newbies who refuse to help themselves.

The funny thing is that their response is to shutdown changes that are
intended
to *help* newbies help themselves. It seems self-defeating to me.

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

Re: Python docs disappointing - group effort to hire writers?

[rurpy]

On Aug 11, 2:46 pm, Mark Lawrence  wrote:
> r wrote:
> > Ah Ha! the docs are broken and i was right all along! Are the good
> > folks at Python dev rolling a new installer as we speak, or we must
> > wait for new version?
>
> As I pointed out a few minutes ago thicko, the new version has been
> available for months.

Now hold on here...

I too was bitten by this.  I thought the chm docs were so unusable
that I went to the issue tracker, extremely annoyed, to submit a
rather caustic bug report.  Only after looking through the doc bugs
did I find that it was already recognised, that a corrected chm
file was available, and that there were no plans to do any more
than that.  (This is from memory since the python tracker is down).

On the main download page is a link to the 2.6.2 msi file with not
a word about the help file.  Only if you follow the "python-2.6.2"
link to a second page, is there a link to the corrected help file,
and even that says only, "Updated Windows help file" with no
indication that it is supposed to replace a broken one in the
distribution.

If "r" is a "thicko", I'd say the handling of this issue was done
by some who are considerably thicker.

It may also be yet another example of how documentation (using
the word loosely) is produced without sufficient attention to its
usefulness to its intended audience.
-- 
http://mail.python.org/mailman/listinfo/python-list

[OT] From: header - WAS: Python docs disappointing - group effort to hire writers?

[Chris Jones]

Hello Paul,

This is strictly OT, but when you get a chance, could you contact me off
list at the above address?

I need your help with the From: email address specified in your posts to
the list. 

Thanks,

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

Re: Python docs disappointing - group effort to hire writers?

[r]

...(Carl Banks doing what he does best)
> > I'm mailing you to kindly request, again, that you please stop
> > validating "r"'s disruptiveness by responding to him on
> > comp.lang.python.  Thank you.

Carl,
You have no right to tell people when where and how they should speak
to anyone. And how dare you think you can! If you spent even a
fraction of the time you spend manipulating the direction of this list
and instead, actually contributing to the problem at hand, (discussion
or otherwise) we would be much closer to solving this problem today.

You (and your conspirators) are the reason most people find the c.l.py
list so disturbing and wish not to participate. Get a life you moron
and stop trying to control the world.

PS: GET STUFFED!
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Mark Lawrence]

Carl Banks wrote:

On Aug 11, 1:46 pm, Mark Lawrence  wrote:

r wrote:

Ah Ha! the docs are broken and i was right all along! Are the good
folks at Python dev rolling a new installer as we speak, or we must
wait for new version?

As I pointed out a few minutes ago thicko, the new version has been
available for months.



Hello,

I'm mailing you to kindly request, again, that you please stop
validating "r"'s disruptiveness by responding to him on
comp.lang.python.  Thank you.

Carl Banks
I hereby apologise.  My only feeble excuse is that my mammary glands are 
getting crushed.


--
Kindest regards.

Mark Lawrence.

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

Re: Python docs disappointing - group effort to hire writers?

[Carl Banks]

On Aug 11, 1:46 pm, Mark Lawrence  wrote:
> r wrote:
> > Ah Ha! the docs are broken and i was right all along! Are the good
> > folks at Python dev rolling a new installer as we speak, or we must
> > wait for new version?
>
> As I pointed out a few minutes ago thicko, the new version has been
> available for months.


Hello,

I'm mailing you to kindly request, again, that you please stop
validating "r"'s disruptiveness by responding to him on
comp.lang.python.  Thank you.

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

Re: Python docs disappointing - group effort to hire writers?

[Mark Lawrence]

r wrote:

Ah Ha! the docs are broken and i was right all along! Are the good
folks at Python dev rolling a new installer as we speak, or we must
wait for new version?
As I pointed out a few minutes ago thicko, the new version has been 
available for months.


--
Kindest regards.

Mark Lawrence.

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

Re: Python docs disappointing - group effort to hire writers?

[r]

Ah Ha! the docs are broken and i was right all along! Are the good
folks at Python dev rolling a new installer as we speak, or we must
wait for new version?
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Mark Lawrence]

r wrote:

Ok people follow me here. Open your winders help file and click the
"Tutorial" link. What is this FLUFF doing here!?!?! Where is the damn
index? Where is the damn tutorial? I want to learn Python not read the
HISTORY OF THE WORLD.

Upon clicking the "Tutorial" link pre 2.6, a nice menu was placed
before your eyes, WHERE IS IT!?!??? Good thing i know the language or
i would have given up already
As I keep on repeating, my version works perfectly.  Perhaps this is 
because I have a computing IQ of approximately 2**32, so realised that 
something was wrong, went here and downloaded the corrected version of 
the file, which has presumably been available for months!


http://www.python.org/download/releases/2.6.2/

And you want newbies let loose on the python docs.  As good ole Santa 
would say, ho, ho, ho!

--
Kindest regards.

Mark Lawrence.

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

Re: Python docs disappointing - group effort to hire writers?

[r]

Ok people follow me here. Open your winders help file and click the
"Tutorial" link. What is this FLUFF doing here!?!?! Where is the damn
index? Where is the damn tutorial? I want to learn Python not read the
HISTORY OF THE WORLD.

Upon clicking the "Tutorial" link pre 2.6, a nice menu was placed
before your eyes, WHERE IS IT!?!??? Good thing i know the language or
i would have given up already
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Grant Edwards]

On 2009-08-11, max bianco  wrote:

> I assume I am misunderstanding you here and you meant something else?
> Python is paraded as a good language for beginners.

I believe it is a good language for beginners.

> Is this a false statement or a secondary objective?

Objective of what?

> Or are the docs only meant for experienced developers?

Some are, some aren't.  The "standard" docs (most of the docs
you can reach directly from http://www.python.org/doc/ --
including the tutorial) aren't intended to teach somebody how
to program and assume the reader has a basic grounding in
programming and language theory.

There are plenty of books and tutorials that are aimed at
teaching programming and Python at the same time.  You can find
some of via the links listed under "Additional documentation"
at http://www.python.org/doc/ -- particularly here:

 http://wiki.python.org/moin/BeginnersGuide/NonProgrammers

> That just doesn't sound right.

-- 
Grant Edwards   grante Yow! My mind is making
  at   ashtrays in Dayton ...
   visi.com
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Grant Edwards]

On 2009-08-11, Paul Rubin  wrote:
> r  writes:
>> Some say the tutorial is not meant for non-programmers, but for
>> programmers with no Python experience. So! How does that justify
>> obstruction of the tut? Why not present the same information in a way
>> both can easily understand? 
>
> I agree that a tutorial for non-programmers would be useful, but it's
> better to have it as a separate document.

There are plenty of docs aimed at non-programmers.  I've heard
this one recommended many times:

http://www.greenteapress.com/thinkpython/

-- 
Grant Edwards   grante Yow! Am I having fun yet?
  at   
   visi.com
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[max bianco]

On Thu, Aug 6, 2009 at 2:36 PM, Kee Nethery wrote:
> As someone trying to learn the language I want to say that the tone on this
> list towards people who are trying to learn Python  feels like it has become
> anti-newbies.
>
> Learning a new language is difficult enough without seeing other newbies
> getting shamed for not knowing everything there is to know about Python
> before asking their questions.

Well I have to say your right about the tone but using google before
you ask is not an unreasonable expectation. I have of course broken
this golden rule myself on mailing lists myself , however a response
like use google is totally acceptable to me.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[max bianco]

On Sat, Aug 8, 2009 at 12:25 AM, Steven
D'Aprano wrote:
> On Fri, 07 Aug 2009 13:35:26 -0700, Kee Nethery wrote:
>
>
>> > Why exactly is posting an open comment on a bug tracker somehow
>> > inferior to posting an open comment on a wiki?
>>
>> It's a good question and deserves a good answer.
>>
>> * Fewer Steps
>> * Immediate
>> * Does not need to be formally reviewed
>> * Easier to search
>
> The last one is actually wrong, because the Python bug tracker is indexed
> by Google.
>
> As for the rest, you're right that the current bug-tracker puts up
> barriers to people submitting comments and bugs. That's actually a good
> thing. The only thing worse than not enough information is too much
> information, and the current situation does a good job of discouraging
> the sorts of people who submit bad bug reports (e.g. duplicates of bug
> reports, bug reports for things fixed years ago, bug reports that are due
> to mistakes in their code, etc.).
>
>
>> For example
>> purposes, I'll use the following page:
>> http://docs.python.org/reference/lexical_analysis.html
>> Lets say the user is in section 2.1.3 Comments
>
> Disclaimer: python.org is down at the moment, so I can't check that page
> to see precisely what you're talking about.
>
>
>> Here's the scenario: The user wanted to include "#" in one of their
>> strings and the IDE kept interpreting it as a comment. But they really
>> need to use that character in the string. Eventually they find out that
>> they can escape the character in their string so that Python stops
>> thinking it is the beginning of a comment.
>
> Er, that would be a bug in the IDE, surely? Inside strings, # is an
> ordinary character with no special meaning.
>
>
 s = "this is a string with an unescaped # in it"
 s
> 'this is a string with an unescaped # in it'
>
>
> The Python docs are supposed to be about Python the language, not work-
> arounds for IDE bugs.
>
>
> [...]
>> Lets assume that Python experts all agree that
>> the docs should get updated with this gotcha (which as a newbie, they
>> are not sure that is a valid assumption and would probably just halt
>> in their quest to get the docs updated).
>
> Good.
>
> As a newbie, you SHOULD assume that anything you think is a bug is
> probably a bug in YOUR code, not Python, and the same goes for
> documentation bugs. If you don't understand something in the docs,
> chances are that it's a problem with you, not the docs. Your first port
> of call should be the tutor list, or here, and not to "fix" the docs by
> putting in noise that just gets in the way of the intended audience,
> namely experienced developers.
>
I assume I am misunderstanding you here and you meant something else?
Python is paraded as a good language for beginners. Is this a false
statement or a secondary objective? Or are the docs only meant for
experienced developers? That just doesn't sound right.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Paul Rubin]

Raymond Hettinger  writes:
> Here is the page specifically marked for those who are new to programming:
>  http://wiki.python.org/moin/BeginnersGuide

Oh cool, I didn't know about that one.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Paul Rubin]

r  writes:
> Some say the tutorial is not meant for non-programmers, but for
> programmers with no Python experience. So! How does that justify
> obstruction of the tut? Why not present the same information in a way
> both can easily understand? 

I agree that a tutorial for non-programmers would be useful, but it's
better to have it as a separate document.  The existing tutorial helps
experienced programmers get started with Python very quickly, by
checking off familiar features from other languages and saying how
Python implements them.  Someone familiar with (say) Java or C++ can
read it in a few minutes and start contributing to a Python project.
Pitching it to complete beginners would require covering a lot of
ground that is already well known to someone who programs in other
languages, and would slow it down too much. 
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Raymond Hettinger]

[Paul Rubin]
> I think the Python tutorial is aimed at users who are newbies to
> Python but not newbies to programming.  Writing a tutorial for total
> newbies is a completely different problem, that would result in a much
> different document that's less useful to the existing tutorial's
> intended audience.

There is more than one right answer to "what is the best tutorial
for different people".  The www.python.org website lists a number
of tutorials.  Here is the page specifically marked for those
who are new to programming:

 http://wiki.python.org/moin/BeginnersGuide


Raymond



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

Re: Python docs disappointing - group effort to hire writers?

[Mark Lawrence]

r wrote:

On Aug 11, 1:47 am, Steven D'Aprano
 wrote:

On Mon, 10 Aug 2009 20:05:00 -0400, David Lyon wrote:

Ignore feedback... tell people to freak off...

Only useless feedback.



[snip]


I am sorry but i feel many here would not judge fairly based on the
merits of an idea without allowing "buddy-systems" or "pecking-orders"
to get in the way. Sad really, only Python suffers in the end.
I disagree with these comments.  I do not believe that Python has a 
buddy system or a pecking order getting in the way of anything.  As you 
are making thsse accusations, either provide hard evidence that can 
persuade me that your perspective on this is correct or shut up.



[snip]




--
Kindest regards.

Mark Lawrence.

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

Re: Python docs disappointing - group effort to hire writers?

[r]

On Aug 11, 1:47 am, Steven D'Aprano
 wrote:
> On Mon, 10 Aug 2009 20:05:00 -0400, David Lyon wrote:
> > Ignore feedback... tell people to freak off...
>
> Only useless feedback.

And who decides what is useless and what isn't Steven?. You?, alex23?,
Bruno?, Paul? Carl? Who makes these decisions and do *they* make them
without pride or prejudice? Do they approve an idea by someone they
hate because it it good, or do they toss it in the trash just to spite
them, because they have the power to do so? As we can see much
resistace exists against even the ideas of change. How will change
ever take place with such defiance!

I am sorry but i feel many here would not judge fairly based on the
merits of an idea without allowing "buddy-systems" or "pecking-orders"
to get in the way. Sad really, only Python suffers in the end.

Some say the tutorial is not meant for non-programmers, but for
programmers with no Python experience. So! How does that justify
obstruction of the tut? Why not present the same information in a way
both can easily understand? I thought Pythons original vision was to
allow easy entry into programming for anybody -- experienced or not!
Anybody remember "CP4E"?

Is this an ivory tower thing? i dunno, but it seems to be...???

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

Re: Python docs disappointing - group effort to hire writers?

[Ethan Furman]

David Lyon wrote:

On Mon, 10 Aug 2009 09:13:34 -0700, Ethan Furman 
wrote:

As someone who relies heavily on the docs I will also say that the idea 
of giving the ability to modify the official documentation to somebody 
who is /learning/ the language is, quite frankly, terrifying.  



What is more terrifying is the way feedback from newbies is handled.

Your statement implies that the only way feedback can be handled is
to throw the keys down in discust and walk away. That's primative
behaviour. And misleading, because that isn't going to happen.



Allow me to put back the sentence you unfairly snipped:
I have no issues with a seperate system, some of which have been 
suggested, but good reference documentation is crucial.  If you find 
examples lacking, there are plenty of web-sites, or even (dare I say

it?) actual hard-copy books!  ;)


To be clear, what I am advocating is that *official documentation not be 
opened up to everybody,* _especially not people who don't yet grok the 
language_.




My bookshelf currently has Learning Python, Programming 
Python, Python Cookbook, Python Programming on Win32, and Regular 
Expressions.  All great books, and not too pricey if you can get them


used.

So, what you're advocating is let things stay how they are...

Ignore feedback... tell people to freak off...




I had not addressed feedback before, but I shall do so now:  Discuss 
concern on the Python list first to make sure it is not a lack of 
understanding, then, if a legitimate issue with the docs exists, use the 
bug tracker.  If one can't be bothered to take the time to be a 
Responsible Citizen, I am not going to be bothered by lacking that one's 
comments/concerns/feed-back.


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

Re: Python docs disappointing - group effort to hire writers?

[Brian]

On Fri, Jul 31, 2009 at 6:12 PM, Kee Nethery  wrote:

> I too find the Python docs not very useful and it really slows down my
> learning curve.
>
> I wonder if it would make sense to find good tech writers, get a quotes,
> and get some professionally written documentation WITH LOTS OF EXAMPLES
> added to the standard Python documentation tree.
>
> I'd chip in money for that task. I've certainly spent enough buying Python
> books to where it would be very reasonable to chip in the cost of one book
> towards this project. Get enough people ... could be a great thing.
>
> Even though it is not the version I use, I would suggest that the really
> detailed docs with lots of examples be written against the latest python
> version.
>
> Just a thought.
>
> Kee Nethery
> --
> http://mail.python.org/mailman/listinfo/python-list
>

One thing I really like about the PHP docs is the built in forums. User
feedback on documentation is invaluable.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Bruno Desthuilliers]

r a écrit :
(snip)


A little note for tutorial writers:
==

Dear Expert,
Whilst writing any tutorial on any subject matter please remember, you
may be an expert, but mostly *non-experts* will be reading your
material... 


I can only second Paul on this : just like the K&R, Python's official 
tutorial targets experienced programmers, not total noobies.


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

Re: Python docs disappointing - group effort to hire writers?

[Steven D'Aprano]

On Mon, 10 Aug 2009 20:05:00 -0400, David Lyon wrote:

> So, what you're advocating is let things stay how they are...

If it's not broken, don't fix it.


> Ignore feedback... tell people to freak off...

Only useless feedback.


-- 
Steven


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

Re: Python docs disappointing - group effort to hire writers?

[Paul Rubin]

r  writes:
> Whilst writing any tutorial on any subject matter please remember, you
> may be an expert, but mostly *non-experts* will be reading your
> material... pssft, this may come as a surprise, but tutorials are
> meant for *NON-EXPERTS*!

I think the Python tutorial is aimed at users who are newbies to
Python but not newbies to programming.  Writing a tutorial for total
newbies is a completely different problem, that would result in a much
different document that's less useful to the existing tutorial's
intended audience.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[David Lyon]

On Mon, 10 Aug 2009 09:13:34 -0700, Ethan Furman 
wrote:
> As someone who relies heavily on the docs I will also say that the idea 
> of giving the ability to modify the official documentation to somebody 
> who is /learning/ the language is, quite frankly, terrifying.  

What is more terrifying is the way feedback from newbies is handled.

Your statement implies that the only way feedback can be handled is
to throw the keys down in discust and walk away. That's primative
behaviour. And misleading, because that isn't going to happen.

> My bookshelf currently has Learning Python, Programming 
> Python, Python Cookbook, Python Programming on Win32, and Regular 
> Expressions.  All great books, and not too pricey if you can get them
used.

So, what you're advocating is let things stay how they are...

Ignore feedback... tell people to freak off...


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

Re: Python docs disappointing - group effort to hire writers?

[r]

On Aug 10, 11:13 am, Ethan Furman  wrote:
(snip)
> As someone who relies heavily on the docs I will also say that the idea
> of giving the ability to modify the official documentation to somebody
> who is /learning/ the language is, quite frankly, terrifying.
(snip)

Ethan,
I think what you and a few others seem to miss is ... Of course nobody
wants Joe-Noob writing the Python docs -- thats lunacy, would you give
your 12 year old the keys to a shiny new corvette? -- No! What people
are asking for is the ability for a noobs input on the official docs,
and for that input to be taken seriously. Sure some of the suggestions
will be nothing more than "helpful ignoramuses" with unhelpful
suggestions as some have said, but the input channels need to be
there. Currently Python dev seems to be more output than input,
however i could be wrong? We some real I/O going on here.

Also the Python tut is full of fluff (sorry Guido) and it contributes
to late learning of the language. Luckily however Python has many
users who really love the language and have taken the time to write
beautiful tutorials that start at various levels of entry. Read xah's
take on the official tutorial, it's spot on baby!

A little note for tutorial writers:
==

Dear Expert,
Whilst writing any tutorial on any subject matter please remember, you
may be an expert, but mostly *non-experts* will be reading your
material... pssft, this may come as a surprise, but tutorials are
meant for *NON-EXPERTS*!

Please refrain from stroking your own ego by obstrufcation of the very
ideas you wish to convey to these influential minds. Sure exposing
your huge intelligence to the world may give you warm-fuzzies-in-your-
tummy, but believe me your poor students will be rendered as helpless
as Paris Hilton at a "panties required" spelling bee.

Please try, and i know this is a lot to ask, to use the most simple
explanation to convey the point -- and *only* the point at hand! Take
for example the introduction of functions. You could go with your gut
instinct, "shoot from the hip" and pop off something like this that
prints a Fibonacci series up to n...

def fib(n):
a, b = 0, 1
while b < n:
print b,
a, b = b, a+b

>>> fib(2000)
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597

And all you would have accomplished was to blow holes thru the
students mind! Now like the next guy, i love calculating series of
numbers all day, but this is a piss poor example of functions for the
new student, or anybody for that matter!  While your student is
racking his brain trying to figure out what "a" and "b" stand for,
much less n, and not to mention what the heck a "Fibonacci" series is
in the first place (Google can help though) , he (the student) has
forgotten that this example is simply how to write and call a
function. A much better example would be the following...

def add(x, y):
print x+y

>>> add(1, 2)
3

WOW,  with that small piece of code you have just transported three
main principals of a function in a very simple and strait forward way
smack-dab into the cerebral cortex of the student, and your fingers
did not even break a sweat!

 1. function names should describe exactly what they do
 2. functions take arguments
 3. functions do something with those arguments(like mini programs!)

You could followup with this fine example that extents on the
first...

def add(x, y=2)
return x+y

>>> add(1,2)

>>> print add(1, 2)
3
>>> print add(1)
3
>>> print add(100, 5.5)
100.5
>>> print add()
error...


However Ethan (and Co.),  not everybody who downloads Python the first
time knows about this. Also the Python website is filled to the brim
with a hodgepodge of "links-here" "links-there", "links-every-freaking-
where" (are we getting paid by the link people?) causing most noobs
brain to start blowing chunks just while tring to find a good
alternative to the official tut!

Really, it's bloat on a proportion that only elephant sized bloat
wares like M$, M$-Office, Adobe-PDF, and the like, can hold a candle
to. Python really needs and enema, and thats no joke!
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Ethan Furman]

Kee Nethery wrote:
As someone trying to learn the language I want to say that the tone on  
this list towards people who are trying to learn Python  feels like it  
has become anti-newbies.


Learning a new language is difficult enough without seeing other  
newbies getting shamed for not knowing everything there is to know  
about Python before asking their questions.


For example, the guy who was looking for Python sample code for the  
Google Map API, calling him a troll was harsh. Suggesting he broach  the 
question to Google was a reasonable answer. By the same token, his  
asking this list about the missing Python examples seems reasonable  
also. Seems to me that people on a Python list might have some  
background knowledge or even samples of the Google Python code that  was 
no longer on the Google web site.


There seems to be a general consensus among the newbies that other  
languages have a user contributions resource tied to the main official  
docs to allow newbies to teach each other what they have learned. The  
desire is for python.org to have the same kind of support resource so  
that us newbies can self support each other.


Kee Nethery


As someone who is (hopefully!) leaving newbieness I can say I have had 
no problem with the helpfullness of this list.  I will also say that 
before I ever posted any questions I had devoured Dive Into Python and 
How To Think Like a Computer Scientist Using Python (both excellent), 
and I try to put as much detail into my questions as I can so nobody has 
to guess what I'm trying to do.


As someone who relies heavily on the docs I will also say that the idea 
of giving the ability to modify the official documentation to somebody 
who is /learning/ the language is, quite frankly, terrifying.  I have no 
issues with a seperate system, some of which have been suggested, but 
good reference documentation is crucial.  If you find examples lacking, 
there are plenty of web-sites, or even (dare I say it?) actual hard-copy 
books!  ;)  My bookshelf currently has Learning Python, Programming 
Python, Python Cookbook, Python Programming on Win32, and Regular 
Expressions.  All great books, and not too pricey if you can get them used.


My $0.02.

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

Re: Python docs disappointing - group effort to hire writers?

[Steven D'Aprano]

On Sat, 08 Aug 2009 20:27:49 +0100, Mark Lawrence wrote:

> Further, I have seen many requests here which are nothing really to do
> with Python, say a query about which algorithm to use.  Response "Not
> really a Python question, but try ...".  Put the same question on (say)
> the C ng and you'd be told in no uncertain terms to Foxtrot Oscar.

We're a lot friendlier than the C newsgroup.

Personally, I think knowing the right algorithm to use is as much a part 
of Python programming as knowing whether to call mystring.upper() or 
string.upper(mystring).


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

Re: Python docs disappointing - group effort to hire writers?

[alex23]

Paul Rubin  wrote:
> Stephen, Alex, etc.: have you actually used the php.net doc system?
> Don't knock it til you've tried it.  IMO it is superior to Python's
> system.  

I've tried it, a lot. Is it okay for me to keep criticising it now, or
would you like some time to find some other allusion to ignorance with
which to wave away my opinion?
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Carl Banks]

On Aug 6, 11:36 am, Kee Nethery  wrote:
> As someone trying to learn the language I want to say that the tone on  
> this list towards people who are trying to learn Python  feels like it  
> has become anti-newbies.

I don't think this NG is anti-newbie so much as anti-whining-loser.

Unfortunately, some newbies might see this and perceive it to be abuse
of newbies in general.  It is not so.  People who have chips on their
shoulder, who make loaded, emotionally-provocative comments, who make
no effort on their own, who expect us to do their homework and/or job
for them, etc., there are the people who going to get an unfavorable
tone.

Newbies who ask respectable questions without having an attitude will
generally get respectable answers.


> For example, the guy who was looking for Python sample code for the  
> Google Map API, calling him a troll was harsh.

No it wasn't, that guy is Xah Lee, a person who's been trolling Usenet
for a long time.  He is best ignored, but I don't blame someone for
snapping at him.


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

Re: Python docs disappointing - group effort to hire writers?

[Mark Lawrence]

Kee Nethery wrote:
As someone trying to learn the language I want to say that the tone on 
this list towards people who are trying to learn Python  feels like it 
has become anti-newbies.



[snip]


Kee Nethery
My gut feeling (which could of course be wrong) is that many hard core 
Pythonistas are cheesed off with newbies who refuse to help themselves.
No evidence that that they've tried any Python tutorial.  No evidence 
that that they've searched anywhere in an attempt to resolve the problem 
before posting.  "This code doesn't work, please fix it".  Response 
often "Please post your actual code, or a snippet that gives the same 
exception, and give the complete exception details".


Show that you have made an attempt to help yourself, and the response 
here is almost certainly 100% helpful.


Further, I have seen many requests here which are nothing really to do 
with Python, say a query about which algorithm to use.  Response "Not 
really a Python question, but try ...".  Put the same question on (say) 
the C ng and you'd be told in no uncertain terms to Foxtrot Oscar.


--
Kindest regards.

Mark Lawrence.

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

Re: Python docs disappointing - group effort to hire writers?

[Roel Schroeven]

Paul Rubin schreef:
> Steven D'Aprano  writes:
>> As for the rest, you're right that the current bug-tracker puts up 
>> barriers to people submitting comments and bugs. That's actually a good 
>> thing. The only thing worse than not enough information is too much 
>> information, and the current situation does a good job of discouraging 
>> the sorts of people who submit bad bug reports (e.g. duplicates of bug 
>> reports, bug reports for things fixed years ago, bug reports that are due 
>> to mistakes in their code, etc.).
> 
> Stephen, Alex, etc.: have you actually used the php.net doc system?
> Don't knock it til you've tried it.  IMO it is superior to Python's
> system.  I don't use PHP much these days.

I have to use PHP from time to time, in which cases I often have to use
the manual on php.net. I don't like it at all.

The official documentation is often incomplete, leaving out the details
I need and forcing me to read the comments.

Which I don't want to do, since many comments show a lack of
understanding of the subject matter. I have to read all of them, trying
to find out which ones are correct and which ones are wrong (or
misleading) to get the complete picture.


I like Python's documentation, where I can be confident that the
documentation is correct (except in the case of the very exceptional
bug) and mostly clear, much better.

-- 
The saddest aspect of life right now is that science gathers knowledge
faster than society gathers wisdom.
  -- Isaac Asimov

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

Re: Python docs disappointing - group effort to hire writers?

[r]

On Aug 7, 12:41 am, alex23  wrote:
...(snip)
> How about a secondary site that embeds the docs and provides
> commenting functionality around it? That's certainly a finitely scoped
> project that those with issues about the docs could establish and
> contribute to, with the possibility of it gaining official support
> later once it gains traction.

This is by far the most helpful and honest post i have ever seen by
our friend alex23. I have a new found respect for you sir, thanks

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

Re: Python docs disappointing - group effort to hire writers?

[Sion Arrowsmith]

Terry Reedy   wrote:
>RayS wrote:
>> http://www.php.net/manual/en/language.types.array.php is a prime example 
>> [ ... ]
>I consider consider this to an unreadable mishmash.
[compared to]
> something compact and readable.

Are you talking about the language or the documentation? 9-)

(Actually, that might be a serious point: does the approach to
documentation reflect language design?)

-- 
\S

   under construction

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

Re: Python docs disappointing - group effort to hire writers?

[Kee Nethery]

As someone trying to learn the language I want to say that the tone on  
this list towards people who are trying to learn Python  feels like it  
has become anti-newbies.


Learning a new language is difficult enough without seeing other  
newbies getting shamed for not knowing everything there is to know  
about Python before asking their questions.


For example, the guy who was looking for Python sample code for the  
Google Map API, calling him a troll was harsh. Suggesting he broach  
the question to Google was a reasonable answer. By the same token, his  
asking this list about the missing Python examples seems reasonable  
also. Seems to me that people on a Python list might have some  
background knowledge or even samples of the Google Python code that  
was no longer on the Google web site.


There seems to be a general consensus among the newbies that other  
languages have a user contributions resource tied to the main official  
docs to allow newbies to teach each other what they have learned. The  
desire is for python.org to have the same kind of support resource so  
that us newbies can self support each other.


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

Re: Python docs disappointing - group effort to hire writers?

[koranthala]

On Aug 7, 5:15 pm, Dave Angel  wrote:
> alex23 wrote:
> > Paul Rubin  wrote:
>
> >> The PHP docs as I remember are sort of regular (non-publically
> >> editable) doc pages, each of which has a public discussion thread
> >> where people can post questions and answers about the topic of that
> >> doc page.  I thought it worked really well.  The main thing is that
> >> the good stuff from the comment section gets folded into the actual
> >> doc now and then.
>
> > I'd still like to see this kept out of the official docs as much as
> > possible, mostly for reasons of brevity & clarity. I think the
> > official docs should be considered definitive and not require a
> > hermeneutic evaluation against user comments to ensure they're still
> > correct...
>
> > How about a secondary site that embeds the docs and provides
> > commenting functionality around it? That's certainly a finitely scoped
> > project that those with issues about the docs could establish and
> > contribute to, with the possibility of it gaining official support
> > later once it gains traction.
>
> I share your concern about unmonitored comments.  However, it seems a
> useful possibility would be for the "official" pages to each have
> specially-marked links that possibly lead to such user comments.  
> Clearly they'd have to marked carefully, so that naive users don't
> confuse the two.  But otherwise, it feels like a good idea.
>
> In my case, I usually access the docs via the Windows help file.  So
> it'd be quite easy for me to recognize that once I've gotten to a
> browser page, I'm not in Kansas any more.  But that could be also
> accomplished by having a very different stylesheet for the user comments
> page.
>
> DaveA

The best example that I have seen is djangobook.
The comment system in it is quite exquisite.
It would be good for the Python docs to have such a mechanism.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Paul Rubin]

Steven D'Aprano  writes:
> As for the rest, you're right that the current bug-tracker puts up 
> barriers to people submitting comments and bugs. That's actually a good 
> thing. The only thing worse than not enough information is too much 
> information, and the current situation does a good job of discouraging 
> the sorts of people who submit bad bug reports (e.g. duplicates of bug 
> reports, bug reports for things fixed years ago, bug reports that are due 
> to mistakes in their code, etc.).

Stephen, Alex, etc.: have you actually used the php.net doc system?
Don't knock it til you've tried it.  IMO it is superior to Python's
system.  I don't use PHP much these days.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Carl Banks]

On Aug 7, 9:25 pm, Steven D'Aprano  wrote:
> If you want an open-access documentation system go right ahead and build
> one. There are plenty of wikis available to use, and the Python docs are
> freely available as your starting point. I might even contribute myself.
> I just don't want it mixed in with the official docs: I want a clear
> separation between what's officially sanctioned and what's not.

The PyGame documentation has a "Click to view comments" box.  That
would be A. low profile, and B. distinct from official documentation
enough for me.

It'd probably be useful, but might also attract spam and lots of
useless fluff, because it's likely to be much higher volume than
documentation on other projects.


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

Re: Python docs disappointing - group effort to hire writers?

[Steven D'Aprano]

On Fri, 07 Aug 2009 13:35:26 -0700, Kee Nethery wrote:


> > Why exactly is posting an open comment on a bug tracker somehow
> > inferior to posting an open comment on a wiki?
> 
> It's a good question and deserves a good answer.
> 
> * Fewer Steps
> * Immediate
> * Does not need to be formally reviewed
> * Easier to search

The last one is actually wrong, because the Python bug tracker is indexed 
by Google.

As for the rest, you're right that the current bug-tracker puts up 
barriers to people submitting comments and bugs. That's actually a good 
thing. The only thing worse than not enough information is too much 
information, and the current situation does a good job of discouraging 
the sorts of people who submit bad bug reports (e.g. duplicates of bug 
reports, bug reports for things fixed years ago, bug reports that are due 
to mistakes in their code, etc.).


> For example  
> purposes, I'll use the following page:
> http://docs.python.org/reference/lexical_analysis.html
> Lets say the user is in section 2.1.3 Comments

Disclaimer: python.org is down at the moment, so I can't check that page 
to see precisely what you're talking about.


> Here's the scenario: The user wanted to include "#" in one of their
> strings and the IDE kept interpreting it as a comment. But they really
> need to use that character in the string. Eventually they find out that
> they can escape the character in their string so that Python stops
> thinking it is the beginning of a comment.

Er, that would be a bug in the IDE, surely? Inside strings, # is an 
ordinary character with no special meaning.


>>> s = "this is a string with an unescaped # in it"
>>> s
'this is a string with an unescaped # in it'


The Python docs are supposed to be about Python the language, not work-
arounds for IDE bugs.


[...]
> Lets assume that Python experts all agree that  
> the docs should get updated with this gotcha (which as a newbie, they  
> are not sure that is a valid assumption and would probably just halt  
> in their quest to get the docs updated).

Good.

As a newbie, you SHOULD assume that anything you think is a bug is 
probably a bug in YOUR code, not Python, and the same goes for 
documentation bugs. If you don't understand something in the docs, 
chances are that it's a problem with you, not the docs. Your first port 
of call should be the tutor list, or here, and not to "fix" the docs by 
putting in noise that just gets in the way of the intended audience, 
namely experienced developers.


> and there is zero confidence that as a newbie, anyone cares about what  
> they found confusing, after all, they are just a newbie and not worthy  
> of altering the documentation. (Certainly that opinion has been  
> expressed several times on this mailing list).

No, we care. We just don't want to have the docs filled with all the hand-
holding and introductory stuff which the newbie needs. As a developer, 
you will outgrow the need for training wheels. Why force training wheels 
on the docs that you will be referring to for your entire career as a 
programmer, when you only need them for the first few months? There are 
plenty of docs aimed at newbies, and mailing lists where you can ask 
questions.

Putting user-comments on a separate page separates the noisy, low-value 
comments from the good stuff, but it increases the efforts needed by the 
webpage admin (who is going to deal with the comment spam? who is going 
to go through the user-comments stripping out the total nonsense put in 
by helpful ignoramuses?). It works for Wikipedia, because there are tens 
of thousands of users contributing small amounts of effort, and hundreds 
putting in a lot of effort, but even there there is a major problem with 
vandalism. We don't have those resources.

By the way, if a person wants to contribute, and can demonstrate 
competence, reliability, good-sense and trustworthiness, there's no 
reason why he or she couldn't get a check-in account for the Python docs. 
(All the Python docs are written by volunteers.) A good way to 
demonstrate these things is by submitting good-quality doc improvements 
to the bug-tracker. If a person can't be bothered to do so, because it 
requires effort to get an account, that goes a long way to demonstrating 
the *lack* of reliability which will disqualify them from the job.


> Very few people would think to search the bug tracking system for help  
> with some specific function. If someone is having trouble with the #  
> sign in their strings, the bug tracking system is not going to be at  
> the top of their list for search locations, especially when the bug  
> tracking system is not mentioned and when found requires a confirmed  
> login.

You don't need a login to view bug reports, only to modify them.

If you want an open-access documentation system go right ahead and build 
one. There are plenty of wikis available to use, and the Python docs are 
freely available as your starting point. I might even cont

Re: Python docs disappointing - group effort to hire writers?

[r]

On Aug 7, 3:35 pm, Kee Nethery  wrote:
(snip)

Kee,
that was an eloquent and enlighting post and i think it speaks volumes
to the lack of inclusion of all Pythoneers in this community. Not to
mention the viscous attitudes and self indulgence we have around here.

For those of you with ADD, Kee was speaking to the hurdles one must
overcome to change even the most minor things within this community.
Change around here almost parallels an act-of-congress with it's de-
motivating burdens that beset a new python user who may wish to add
his or her 2 pennies to the Python wishing well. And i believe like
Kee, most of them just give up and say
   """Oh Well, F### it!"""

Not to mention the never ending droves of naysayers, bullies, smart-
arses, and egomaniacs with their minions and sock-puppets ready at
moments notice to pounce on (and utterly destroy) any feeble noob who
dares to try and enhance the user experience in Python for all of us.

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

Re: Python docs disappointing - group effort to hire writers?

[Kee Nethery]

On Aug 7, 2009, at 10:48 AM, alex23 wrote:


Kee Nethery  wrote:

I'm looking forward to the acceleration of improvements to the
official docs based upon easy to provide user feedback. Glad to see
that the bug tracking system is going to not be the primary means for
documentation changes.


I'm not sure what you see as being fundamentally different between
open access to a bug tracker & open access to a wiki, other than it
being a lot more difficult to have threaded discussion on a wiki.

Why exactly is posting an open comment on a bug tracker somehow
inferior to posting an open comment on a wiki?


It's a good question and deserves a good answer.

* Fewer Steps
* Immediate
* Does not need to be formally reviewed
* Easier to search

For all these comments, assume the starting point is the section in a  
web page that documents a specific python function. Assume the user is  
using the documentation for the first time in attempt to convert to  
Python. Thus, this is the only official Python page they have ever  
seen, they found it via Google and went directly to it. For example  
purposes, I'll use the following page:

http://docs.python.org/reference/lexical_analysis.html
Lets say the user is in section 2.1.3 Comments

Here's the scenario: The user wanted to include "#" in one of their  
strings and the IDE kept interpreting it as a comment. But they really  
need to use that character in the string. Eventually they find out  
that they can escape the character in their string so that Python  
stops thinking it is the beginning of a comment. They want other users  
to not suffer through the same thing, and they want to contribute to  
the betterment of Python, so they want this information saved so that  
others can avoid the mistake they were making.


* Fewer Steps:

With the bug tracking system, their only option is to lobby to get the  
documentation changed. Lets assume that Python experts all agree that  
the docs should get updated with this gotcha (which as a newbie, they  
are not sure that is a valid assumption and would probably just halt  
in their quest to get the docs updated). But assuming everyone agrees  
this is a valuable addition to the docs so that others can avoid the  
same error, where on this page dues the user submit this bug? There is  
no link on this page to the bug tracking system.


Lets assume they find the bug tracking system through determined  
efforts because they believe there has to be such a thing and they are  
absolutely sure the powers that be want their input. When they find  
the bug tracking system ... they have to create a user account. Then  
they have to wait for the confirming email. Finally they get access to  
the bug tracking system and being a good citizen, they want to make  
sure that they are not duplicating a previously entered bug. What do  
they search on? Do they search for 2.1.3? Do they search for "#"?  
Chances are, even if they do a whole set of searches, and if there  
really is already another bug entered for the exact same issue, they  
are unlikely to find it.


So they create a bug and now they need to go back and reference the  
link (find the page from their browser history) and type up why they  
think their modification to the documentation is worthy. Then once the  
bug is submitted ... you get the picture, there are a gazillion steps  
just to submit a bug. Most people do not bother to submit little  
helpful hints to the docs because it is too much of a pain to do so  
and there is zero confidence that as a newbie, anyone cares about what  
they found confusing, after all, they are just a newbie and not worthy  
of altering the documentation. (Certainly that opinion has been  
expressed several times on this mailing list).


With a wiki article tied to each section in the docs, they click on  
the link and are taken directly to the wiki page of user contributions  
for this specific  2.1.3 section of the docs. They scan the user  
comments and see that no one else entered a note about this gotcha.  
They click on the edit button, enter their gotcha, save, and they are  
done.


* Immediate:

With the bug tracking system, they struggle to find a place to  
contribute and then once they make their contribution, they have no  
idea whether anyone will ever see it and whether they have just wasted  
a bunch of time.


With the wiki link for that section, in less than a minute, they can  
see the comments they have left attached to that specific section so  
that others can see them too and perhaps avoid the same mistake they  
made. A wiki link encourages new users to be contributors. New users  
are the absolute best source of what is confusing to a new user.


* Does not need to be formally reviewed:

With the bug tracking system, each bug has to be reviewed by a  
volunteer, analyzed, commented on, dealt with.


With a wiki, no one has to look at user comments. They can just leave  
them there and ignore them. Other users can pol

Re: Python docs disappointing - group effort to hire writers?

[alex23]

David Robinow  wrote:
>  When one believes that development is controlled by a cabal which is
> jealous of outsiders and actively prevents improvements to the docs,
> any change, even if only in perception, helps to weaken the hold of
> the evil forces holding back the success of Python.

Yeah, it's clearly all ego and assholes that's preventing Python from
being the enochian equivalent of programming languages :)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[David Robinow]

On Fri, Aug 7, 2009 at 1:48 PM, alex23 wrote:
> Why exactly is posting an open comment on a bug tracker somehow
> inferior to posting an open comment on a wiki?
 When one believes that development is controlled by a cabal which is
jealous of outsiders and actively prevents improvements to the docs,
any change, even if only in perception, helps to weaken the hold of
the evil forces holding back the success of Python.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[alex23]

Kee Nethery  wrote:
> I'm looking forward to the acceleration of improvements to the  
> official docs based upon easy to provide user feedback. Glad to see  
> that the bug tracking system is going to not be the primary means for  
> documentation changes.

I'm not sure what you see as being fundamentally different between
open access to a bug tracker & open access to a wiki, other than it
being a lot more difficult to have threaded discussion on a wiki.

Why exactly is posting an open comment on a bug tracker somehow
inferior to posting an open comment on a wiki?
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[r]

On Aug 7, 11:03 am, Kee Nethery  wrote:
...(snip)
> I'm looking forward to the acceleration of improvements to the  
> official docs based upon easy to provide user feedback. Glad to see  
> that the bug tracking system is going to not be the primary means for  
> documentation changes.

+1

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

Re: Python docs disappointing - group effort to hire writers?

[Kee Nethery]

During all this conversation there was a ticket posted in the bug  
tracking system with the suggestion of each section in the official  
docs linking to a fixed wiki page that can contain user contributions.


The ticket has been closed because this addition to the official docs  
is already in the works.


So ... to everyone who thinks there needs to be a place for user  
comments to augment the official docs, it's supposed to happen. Same  
with corrections to the docs, there is supposed to be a place per  
section where people can post corrections to the docs.


I'm looking forward to the acceleration of improvements to the  
official docs based upon easy to provide user feedback. Glad to see  
that the bug tracking system is going to not be the primary means for  
documentation changes.


Kee

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

Re: Python docs disappointing - group effort to hire writers?

[alex23]

Paul Rubin  wrote:
> Such evaluation would only do them good.  The official docs are full
> of errors and omissions, which is why we have this thread going on
> here in the newsgroup.

And there is a process for reporting and correcting such errors and
omissions, which is what I pointed out in my post.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Dave Angel]

alex23 wrote:

Paul Rubin  wrote:
  

The PHP docs as I remember are sort of regular (non-publically
editable) doc pages, each of which has a public discussion thread
where people can post questions and answers about the topic of that
doc page.  I thought it worked really well.  The main thing is that
the good stuff from the comment section gets folded into the actual
doc now and then.



I'd still like to see this kept out of the official docs as much as
possible, mostly for reasons of brevity & clarity. I think the
official docs should be considered definitive and not require a
hermeneutic evaluation against user comments to ensure they're still
correct...

How about a secondary site that embeds the docs and provides
commenting functionality around it? That's certainly a finitely scoped
project that those with issues about the docs could establish and
contribute to, with the possibility of it gaining official support
later once it gains traction.


  
I share your concern about unmonitored comments.  However, it seems a 
useful possibility would be for the "official" pages to each have 
specially-marked links that possibly lead to such user comments.  
Clearly they'd have to marked carefully, so that naive users don't 
confuse the two.  But otherwise, it feels like a good idea.


In my case, I usually access the docs via the Windows help file.  So 
it'd be quite easy for me to recognize that once I've gotten to a 
browser page, I'm not in Kansas any more.  But that could be also 
accomplished by having a very different stylesheet for the user comments 
page.


DaveA

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

Re: Python docs disappointing - group effort to hire writers?

[Paul Rubin]

alex23  writes:
> I'd still like to see this kept out of the official docs as much as
> possible, mostly for reasons of brevity & clarity. I think the
> official docs should be considered definitive and not require a
> hermeneutic evaluation against user comments to ensure they're still
> correct...

Such evaluation would only do them good.  The official docs are full
of errors and omissions, which is why we have this thread going on
here in the newsgroup.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Jean-Michel Pichavant]

alex23 wrote:

Paul Rubin  wrote:
  

The PHP docs as I remember are sort of regular (non-publically
editable) doc pages, each of which has a public discussion thread
where people can post questions and answers about the topic of that
doc page.  I thought it worked really well.  The main thing is that
the good stuff from the comment section gets folded into the actual
doc now and then.



I'd still like to see this kept out of the official docs as much as
possible, mostly for reasons of brevity & clarity. I think the
official docs should be considered definitive and not require a
hermeneutic evaluation against user comments to ensure they're still
correct...

How about a secondary site that embeds the docs and provides
commenting functionality around it? That's certainly a finitely scoped
project that those with issues about the docs could establish and
contribute to, with the possibility of it gaining official support
later once it gains traction.



  
Very good Idea. I'd like to get a commented/user improved python 
documentation site with examples and I also love the current python 
documentation.


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

Re: Python docs disappointing - group effort to hire writers?

[alex23]

Paul Rubin  wrote:
> The PHP docs as I remember are sort of regular (non-publically
> editable) doc pages, each of which has a public discussion thread
> where people can post questions and answers about the topic of that
> doc page.  I thought it worked really well.  The main thing is that
> the good stuff from the comment section gets folded into the actual
> doc now and then.

I'd still like to see this kept out of the official docs as much as
possible, mostly for reasons of brevity & clarity. I think the
official docs should be considered definitive and not require a
hermeneutic evaluation against user comments to ensure they're still
correct...

How about a secondary site that embeds the docs and provides
commenting functionality around it? That's certainly a finitely scoped
project that those with issues about the docs could establish and
contribute to, with the possibility of it gaining official support
later once it gains traction.



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

Re: Python docs disappointing - group effort to hire writers?

[r]

On Aug 6, 11:20 am, Paul Rubin  wrote:
...(snip)
> There is something similar with the PostgreSQL docs.  There is also
> Real World Haskell (http://book.realworld.haskell.org) which has a lot
> of interspersed user comments.  It would be cool if Python's doc site
> did something like it too.

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

Re: Python docs disappointing - group effort to hire writers?

[Paul Rubin]

alex23  writes:
> No offence, but the last thing the official documentation needs is
> example code written by people learning how to code. Suggest changes,
> request clarifications, submit samples for review, sure, but direct
> modification by users? I've seen the PHP docs; thanks but no thanks.

The PHP docs as I remember are sort of regular (non-publically
editable) doc pages, each of which has a public discussion thread
where people can post questions and answers about the topic of that
doc page.  I thought it worked really well.  The main thing is that
the good stuff from the comment section gets folded into the actual
doc now and then.

There is something similar with the PostgreSQL docs.  There is also
Real World Haskell (http://book.realworld.haskell.org) which has a lot
of interspersed user comments.  It would be cool if Python's doc site
did something like it too.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[alex23]

Kee Nethery wrote:
> As I struggle through trying to figure out how to make python do  
> simple stuff for me, I frequently generate samples. If some volunteer  
> here would point me towards the documentation that would tell me how I  
> can alter the existing Python docs to include sample code, I'd be more  
> than happy to do so.

No offence, but the last thing the official documentation needs is
example code written by people learning how to code. Suggest changes,
request clarifications, submit samples for review, sure, but direct
modification by users? I've seen the PHP docs; thanks but no thanks.

> I would like to "do it". Please point me to the docs that tell me how  
> to "do it" so that we people with newbie questions and a need for  
> examples can get out of your way and "do it" ourselves.

You start by reading this: http://docs.python.org/documenting/index.html
And this: http://www.python.org/dev/contributing/
And this: http://wiki.python.org/moin/WikiGuidelines

The first link, which directly answers your question, is clearly
listed on the doc contents page as "Documenting Python". I'm uncertain
how the docs could be made any _more_ helpful if people aren't
prepared to put effort into reading them. We're a long way away from
direct upload to the brain, unfortunately.

If you're learning the language, you should also consider using more
appropriate resources:
http://mail.python.org/mailman/listinfo/tutor
http://www.doughellmann.com/PyMOTW/
http://diveintopython.org/

The documentation cannot be all things to all people, and it most
certainly can't be a guide to general programming, which is what often
seems to be the issue with novice users. Python's a great language to
learn how to program in, sure, but I would hate to see that become the
focus of the docs.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Kee Nethery]

On Aug 6, 2009, at 6:55 AM, Terry Reedy wrote:


RayS wrote:

At 08:35 PM 8/5/2009 -0700, r wrote:

"""... Any real sense of community is undermined -- or
even destroyed -- to be replaced by virtual equivalents that strive,
unsuccessfully, to synthesize a sense of community."""
I've brought up the idea of the quasi-community doc that PHP uses  
to good effect.


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

http://www.php.net/manual/en/language.types.array.php is a prime  
example where 2/3 of the "doc" is user-contributed comments and code.


I consider consider this to an unreadable mishmash. If you and  
others want something like that, do it.  And quite bitching about  
the work of those of us who have done something compact and  
readable. We are all volunteers here.


As I struggle through trying to figure out how to make python do  
simple stuff for me, I frequently generate samples. If some volunteer  
here would point me towards the documentation that would tell me how I  
can alter the existing Python docs to include sample code, I'd be more  
than happy to do so.


I would like to "do it". Please point me to the docs that tell me how  
to "do it" so that we people with newbie questions and a need for  
examples can get out of your way and "do it" ourselves.


Thanks,
Kee Nethery



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

Re: Python docs disappointing - group effort to hire writers?

[Terry Reedy]

RayS wrote:

At 08:35 PM 8/5/2009 -0700, r wrote:

"""... Any real sense of community is undermined -- or
even destroyed -- to be replaced by virtual equivalents that strive,
unsuccessfully, to synthesize a sense of community."""


I've brought up the idea of the quasi-community doc that PHP uses to 
good effect.


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

http://www.php.net/manual/en/language.types.array.php is a prime example 
where 2/3 of the "doc" is user-contributed comments and code.


I consider consider this to an unreadable mishmash. If you and others 
want something like that, do it.  And quite bitching about the work of 
those of us who have done something compact and readable. We are all 
volunteers here.


tjr

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

Re: Python docs disappointing - group effort to hire writers?

[RayS]

At 08:35 PM 8/5/2009 -0700, r wrote:
"""... Any real
sense of community is undermined -- or
even destroyed -- to be replaced by virtual equivalents that 
strive,
unsuccessfully, to synthesize a sense of
community."""
I've brought up the idea of the quasi-community doc
that PHP uses to good effect.
http://www.php.net/manual/en/language.types.array.php
is a prime example where 2/3 of the "doc" is user-contributed comments and code. 
http://www.php.net/manual/en/about.notes.php 
"By allowing readers of the manual to contribute examples, caveats, and further clarifications from their browser, we are able to incorporate that feedback into the main text of the manual. And until the notes have been incorporated, they may be viewed in their submitted form online, and in some of the offline formats. "
The terseness or non-clarity of a doc is quickly remedied by numerous User Contributed Notes, and over the years, they have rolled these contributed examples into the "official" doc section. While I hardly do much PHP any more, when I do need to perform maintenance etc. it is THE invaluable resource, and I believe an important part of PHP's enduring popularity.
Language arguments aside http://docs.python.org/library/array.html, for instance, would benefit from such community.



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

Re: Python docs disappointing - group effort to hire writers?

[r]

On Aug 4, 12:55 am, David Lyon  wrote:
> It isn't totally about the writers...
> Peoples egos are also at stake - it seems.
> If "Fred X wrote Doc Y".. they don't want their name taken off.. So
> they generally speaking don't want the docs changed.
> If you talk too much about docs.. you can be told you're OT..
> even in a thread about docs...

This is the most honest post within this thread. Yes i believe --
although it does not make me happy-- that many within this community
are hostile, vulgar, and viscous towards any notion of change if it
comes from outside the "insiders" group (and even sometimes from the
inside). Which is very sad.

Yes sometimes people are just trolling, but this tread has nothing to
do with trolling. kj has a legitimate complaint. Do i believe the docs
are a complete waste of bytes, No! Many people have invested tons of
hard work into them (and i thank them for their hard work). But i do
believe --like all things in this word-- perfection is always just out
of hands reach, we must constantly seek perfection because we can
never attain it. Like any group effort, eventually it will adopt the
idioms of self indulgence. Python dev needs the input of those who are
not experts in the language --especially in the realm of docs.

It is so easy to forget the struggles we face when learning something
new. The accessibility and appeal of Python to new users is in the
best interest of this community. If you don't believe that, you are
pissing on all the years of hard work that has been put in here. You
might as well just tell Guido to "close up shop"

I have posted this once before but i will post it again. Please read
Christopher's words carefully because they apply to this community in
a big way...Don't fall into the trap of narcissism.

Christopher Lasch referring to the pitfalls of Narcissistic societies:

"""In such a society of constant competition, there can be no allies,
and little transparency. The threats to
acquisitions of social symbols are so numerous, varied and frequently
incomprehensible, that defensiveness, as well as competitiveness,
becomes a way of life. Any real sense of community is undermined -- or
even destroyed -- to be replaced by virtual equivalents that strive,
unsuccessfully, to synthesize a sense of community."""

While I agree that some narcissism is vital to an individuals ego in
competitive atmospheres, I do not believe the Python community
warrants this need.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[alex23]

On Aug 4, 3:55 pm, David Lyon  wrote:
> It isn't totally about the writers...
> Peoples egos are also at stake - it seems.

Citation please.

> If "Fred X wrote Doc Y".. they don't want their name taken off.. So
> they generally speaking don't want the docs changed.

Ditto.

> If you talk too much about docs.. you can be told you're OT..
> even in a thread about docs...

And again.

All I've _ever_ seen (on this group at least) is the much repeated
phrase "All patches to the docs are welcomed". If you'd like to cast
aspersions on the characters of those doing the work over actually
contributing yourself, you're certainly free to do so, just don't
expect your claims to be taken seriously.

Other people's refusal to do the work that _you_ consider to be
necessary isn't "ego".
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[David Lyon]

It isn't totally about the writers...

Peoples egos are also at stake - it seems.

If "Fred X wrote Doc Y".. they don't want their name taken off.. So
they generally speaking don't want the docs changed.

If you talk too much about docs.. you can be told you're OT..

even in a thread about docs...

On Fri, 31 Jul 2009 17:12:43 -0700, Kee Nethery  wrote:
> I too find the Python docs not very useful and it really slows down my  
> learning curve.
> 
> I wonder if it would make sense to find good tech writers, get a  
> quotes, and get some professionally written documentation WITH LOTS OF  
> EXAMPLES added to the standard Python documentation tree.
> 
> I'd chip in money for that task. I've certainly spent enough buying  
> Python books to where it would be very reasonable to chip in the cost  
> of one book towards this project. Get enough people ... could be a  
> great thing.
> 
> Even though it is not the version I use, I would suggest that the  
> really detailed docs with lots of examples be written against the  
> latest python version.
> 
> Just a thought.
> 
> Kee Nethery
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Python docs disappointing - group effort to hire writers?

[Kee Nethery]

I too find the Python docs not very useful and it really slows down my  
learning curve.


I wonder if it would make sense to find good tech writers, get a  
quotes, and get some professionally written documentation WITH LOTS OF  
EXAMPLES added to the standard Python documentation tree.


I'd chip in money for that task. I've certainly spent enough buying  
Python books to where it would be very reasonable to chip in the cost  
of one book towards this project. Get enough people ... could be a  
great thing.


Even though it is not the version I use, I would suggest that the  
really detailed docs with lots of examples be written against the  
latest python version.


Just a thought.

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