subject:"Re\: Bitching about the documentation..."

On Mon, 05 Dec 2005 19:36:58 -0800, BartlebyScrivener wrote:

 Well, that might be asking a bit too much of the programmers, who
 perhaps don't exactly enjoy mucking about in the lowlands of English
 grammar and syntax.

Oh come on now! For the kinds of minds who enjoy obfuscated C or Perl,
English is just par for the course.

One of my favourite examples of obfuscated English is this grammatically
correct sentence:

Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.

And they say English is a hard language to understand :-)

On the other hand, for programmers who don't like obfuscated anything,
English can be as precise and elegant as anything in Lisp or Python. Treat
English as a programming language: learn the rules of syntax and grammar,
and read examples of master writers to learn the best idioms, and you
can't go wrong.

But if you try to learn English from Usenet... *shudders*


-- 
Steven.

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

Re: Bitching about the documentation...

Steven D'Aprano wrote:

 Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.

Did you mean: Badger badger Badger badger badger badger Badger badger Mushroom! 
Mushroom!

/F



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

Re: Bitching about the documentation...

On Mon, 05 Dec 2005 21:05:46 -0800, rurpy wrote:

 If one is required to buy a book to use free software, 

One is *not* required to buy a book to use free software. It isn't
compulsory.

 it is not really free, is it?

What part of you may use this FREE software for FREE is too difficult
for you to understand?

If you want to calculate the total cost of ownership for (say) using
Python, then by all means include the cost of labour, electricity to run
your computer, depreciation on that computer, courses to learn how to
program, etc. All these are valid costs.

But none of them are the cost of Python, which is free. It really isn't a
scam, nobody is going to come knocking at your door with a surprise bill
for using Python.



-- 
Steven.

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

Re: Bitching about the documentation...

2005-12-07 Thread skip


 This is why things need to go into public trackers, or wiki pages.

François Whatever means the maintainer wants to fill his preservation
François needs, he is free to use them.  The problem arises when the
François maintainer wants imposing his own work methods on others.

François, that's not it at all.  It's not our fault that SF doesn't support
email-based tracker interaction.  It's our fault that we chose SF, but it
was the best overall choice at the time (there were more considerations than
just bug tracking) and now we're sort of stuck with it because for a number
of reasons we've been unable to move away from it.

Here's the scenario we have to use today to collect emailed requests and put
them in SF:

* Kind user notices a problem and posts a message somewhere, maybe to c.l.py
  or to another Python-related list or by direct email to a developer.

* Someone - maybe nobody, but maybe more than one person - notices the
  request and thinks, better add that to SF so it doesn't get lost.

* That person visits SF and submits a ticket.

Now, consider some of the problems this scheme is fraught with:

* Maybe nobody notices it at all.  It might have been buried deep in another
  thread that no Python developer happened to read in its entirety.  Bummer.
  It's been lost until the next time someone notices and posts a similar
  request.

* Maybe more than one person notices.  Bummer.  Now we have duplicates.
  Worse yet, some might have been posted as feature requests, some as bug
  reports.  It also may not be obvious that they are duplicate without
  careful checking.

* The multiple reports might contain different useful perspectives on the
  problem.  Bummer.  SF doesn't allow you to easily merge two requests.  You
  have to manually transfer the information from one to the other and close
  the one.

* Maybe the original post generates further responses in that venue that
  would have been useful to have with the original report.  Most will
  probably never find their way to the tracker.  Bummer.  They got lost.

* Maybe the original requester's email gets missed in the process (or the
  problem isn't addressed immediately and the user has discarded the
  original address because it's spammed so heavily and moved on to a new
  one) and the Python developers need more info but they can't contact the
  requester.  Bummer.  The problem isn't adequately addressed.

* Finally, instead of one person spending a couple minutes submitting a
  report, several people will have spent their volunteer time, and there's a
  good chance that the report is not any better (perhaps even worse) than if
  the original requester had simply submitted the request directly to SF.

I know, we have to take these steps occasion.  When bug reports have to be
moved from another tracker to the Python tracker some of these issues arise.
We've incorportated bug reports from the Debian bug tracker that way and
have migrated python-mode requests from the Python project to the
python-mode project (both on SF).  It can be a pain.

The Python developers are not being lazy.  I would love it if there was an
email interaction mode with the SF trackers, but there isn't.  I'll repeat
what I wrote yesterday in response to an earlier message in this thread:

I wish either a) SourceForge supported email interaction with their
trackers or b) someone would finish off the Roundup issue tracker
http://roundup.sourceforge.net/ for python.org.  I doubt if anyone
here can do anything about the first barrier, but if you know something
about Roundup (or would like to learn about it) and would like to
contribute something non-documentational that would really have a
direct, positive impact on the Python community, send a note to
[EMAIL PROTECTED]

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

Re: Bitching about the documentation...

2005-12-07 Thread Simon Brunning

On 12/7/05, Steven D'Aprano [EMAIL PROTECTED] wrote:
 But none of them are the cost of Python, which is free. It really isn't a
 scam, nobody is going to come knocking at your door with a surprise bill
 for using Python.

Well, there is the PSU's Spanish Inquisition division. Last week
they barged into my office, quite unexpectedly, armed with cushions
and
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Usenet falsehoods (was Re: Bitching about the documentation...)

[EMAIL PROTECTED] wrote:

   Real people have real names.  Using your real name on the net makes
   you less virtual to the people you communicate with.

on the other hand,

http://www.python.org/doc/Humor.html#timbot2

/F 



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

Re: Bitching about the documentation...

2005-12-07 Thread Jon Perez

Tony Meyer wrote:

 This makes no sense.  If you want to complain about Python, try a  
 Perl list.  Why would a list dedicated to discussion about/help with  
 a language need complaints about the language?

Huh?!?  Usually people complain because they need help or feel
that things can be improved.

 You might want to consider the difference between complaining and  
 constructive criticism and suggestions, and which are likely to get  
 better responses.

In the case of programming languages, I don't see any real difference
between something being a 'constructive criticism' and a 'complaint'.

Why, oh why, do so many programmers insist on elevating software tools
they are using to the status of a *religion* such that they feel personally
offended when someone badmouths the language or tool they are using???

Anyone can badmouth Python and things associated with all they want, the
only time it would even begin to bother me is only if these were false
accusations or there is a dishonest agenda behind it.

If the complaints are untrue, then I'd just be laughing at others'
ignorance, not be offended by it.  If it is an honest complaint
arising out of personal experience with the language, then certainly
there is a need to examine what can be improved.

I generally don't see any need to feel uncomfortable with strident
whining against Python because the only thing being attacked here is a
software tool, not persons.

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

Re: Bitching about the documentation...

2005-12-07 Thread Christopher Subich

Fredrik Lundh wrote:
 Steven D'Aprano wrote:
 
 
Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.
 
 
 Did you mean: Badger badger Badger badger badger badger Badger badger 
 Mushroom! Mushroom!

Thank you, I really needed that stuck in my head. :)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

2005-12-07 Thread Grant Edwards

On 2005-12-07, Steven D'Aprano [EMAIL PROTECTED] wrote:
 On Mon, 05 Dec 2005 19:36:58 -0800, BartlebyScrivener wrote:

 Well, that might be asking a bit too much of the programmers, who
 perhaps don't exactly enjoy mucking about in the lowlands of English
 grammar and syntax.

 Oh come on now! For the kinds of minds who enjoy obfuscated C or Perl,
 English is just par for the course.

 One of my favourite examples of obfuscated English is this grammatically
 correct sentence:

 Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.

Why the goofy-looking capitalization?  Are the 2nd and 3rd
occurances of Buffalo referring to the city?

-- 
Grant Edwards   grante Yow!  All of life is a blur
  at   of Republicans and meat!
   visi.com
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

2005-12-07 Thread Alex Martelli

Steven D'Aprano [EMAIL PROTECTED] wrote:

 On Mon, 05 Dec 2005 19:36:58 -0800, BartlebyScrivener wrote:
 
  Well, that might be asking a bit too much of the programmers, who
  perhaps don't exactly enjoy mucking about in the lowlands of English
  grammar and syntax.
 
 Oh come on now! For the kinds of minds who enjoy obfuscated C or Perl,
 English is just par for the course.

As it happens, there appears to be pretty weak correlation between
proficiency in programming and proficiency in writing -- SOME excellent
programmers are great writers too, but, I would guess, just roughly the
same percentage as in the general popularion (i.e., deucedly few).


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

Re: Bitching about the documentation...

2005-12-07 Thread Jon Perez

[EMAIL PROTECTED] wrote:

 FWIW I find Python's docs to be OK at best, with some horrible
 parts, and a lot of mediochre to poor parts.

I myself have no big beef about Python's docs, but you're certainly
not the first one to complain about them.  Xah Lee rants very
heavily against the quality against Python's docs and considers
many sections of it as written in a manner more to show-off one's
knowledge of jargon rather than to explain things properly.

I don't really notice that but this could be because I'm already
quite comfortable with jargon at the level it is used in the
Python docs (or maybe I'm one of those highfalutin' chaps as well
;-D).  Seriously though, sometimes jargon is necessary in order to
put across a point concisely and accurately so its use cannot always
be considered gratuitous.

The only problem I have with Python docs is that for most of
the the standard library API documentation, the function calls
are not organized very well (i.e. I don't believe they are
alphabetized or ordered in any intutive manner).

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

Re: Bitching about the documentation...

On Wed, 07 Dec 2005 07:50:14 -0800, Alex Martelli wrote:

 Steven D'Aprano [EMAIL PROTECTED] wrote:
 
 On Mon, 05 Dec 2005 19:36:58 -0800, BartlebyScrivener wrote:
 
  Well, that might be asking a bit too much of the programmers, who
  perhaps don't exactly enjoy mucking about in the lowlands of English
  grammar and syntax.
 
 Oh come on now! For the kinds of minds who enjoy obfuscated C or Perl,
 English is just par for the course.
 
 As it happens, there appears to be pretty weak correlation between
 proficiency in programming and proficiency in writing -- SOME excellent
 programmers are great writers too, but, I would guess, just roughly the
 same percentage as in the general popularion (i.e., deucedly few).


If you know any links to real research on this, I'd love to learn more.
I'm always amazed and perplexed at how hot-shot programmers who would
never forget a colon or a brace can be so slap-dash about using proper
punctuation and grammar in English.


-- 
Steven.

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

Re: Bitching about the documentation...

On Wed, 07 Dec 2005 15:29:07 +, Grant Edwards wrote:

 On 2005-12-07, Steven D'Aprano [EMAIL PROTECTED] wrote:
 On Mon, 05 Dec 2005 19:36:58 -0800, BartlebyScrivener wrote:

 Well, that might be asking a bit too much of the programmers, who
 perhaps don't exactly enjoy mucking about in the lowlands of English
 grammar and syntax.

 Oh come on now! For the kinds of minds who enjoy obfuscated C or Perl,
 English is just par for the course.

 One of my favourite examples of obfuscated English is this grammatically
 correct sentence:

 Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.
 
 Why the goofy-looking capitalization?  Are the 2nd and 3rd
 occurances of Buffalo referring to the city?

The punctuation is important. Yes, they refer to the city.

(Which reminds me of the old joke about capitalisation being the
difference between I helped my Uncle Jack off a horse and I helped my
Uncle jack off a horse.)

For those who don't know, buffalo is also a verb meaning to overwhelm
or intimidate.



S
P
O
I
L
E
R
 
S
P
A
C
E



Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.

Buffalo from the city of Buffalo, which are intimidated by buffalo
from Buffalo, also intimidate buffalo from Buffalo.


I didn't say it was *good* English, but it is *legal* English.



-- 
Steven.

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

Re: Bitching about the documentation...

On Wed, 07 Dec 2005 11:45:04 +0100, Fredrik Lundh wrote:

 Steven D'Aprano wrote:
 
 Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.
 
 Did you mean: Badger badger Badger badger badger badger Badger badger 
 Mushroom! Mushroom!

Er... no, I can't parse that. I suffered a Too Much Recursion error about
the third Badger (I only have a limited runtime stack).

I asked my missus about this one, she being much better at English grammar
than I am, and she thinks the badger/mushroom sentence is a wind-up. Is
she right?


-- 
Steven.

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

Re: Bitching about the documentation...

2005-12-07 Thread Christopher Subich

Steven D'Aprano wrote:

 S
 P
 O
 I
 L
 E
 R
  
 S
 P
 A
 C
 E
 
 
 
 Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.
 
 Buffalo from the city of Buffalo, which are intimidated by buffalo
 from Buffalo, also intimidate buffalo from Buffalo.

And to do a small simplification on it, to illustrate just how painful 
that sentence really is, the semantically equivalent version:

N = buffalo from Buffalo

(N [that] N buffalo) buffalo N.

The dropping of the [that] is legal, if sometimes ambiguous, in English.

 I didn't say it was *good* English, but it is *legal* English.

Which is why natural language programming's never going to take off. :)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

Steven D'Aprano wrote:

 S
 P
 O
 I
 L
 E
 R

 S
 P
 A
 C
 E



 Buffalo from the city of Buffalo, which are intimidated by buffalo
 from Buffalo, also intimidate buffalo from Buffalo.

Did you mean:  Bagder from the city of Badger, who is pestered by
a badger from Badger, also pesters badger from Badger.  Mushroom
expands rapidly!

(Argh! Snake!)

/F



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

Re: Bitching about the documentation...

2005-12-07 Thread Christopher Subich

Steven D'Aprano wrote:
 On Wed, 07 Dec 2005 11:45:04 +0100, Fredrik Lundh wrote:
 
Did you mean: Badger badger Badger badger badger badger Badger badger 
Mushroom! Mushroom!
 
 
 Er... no, I can't parse that. I suffered a Too Much Recursion error about
 the third Badger (I only have a limited runtime stack).

http://www.badgerbadgerbadger.com/

And now back to your regularly scheduled newsgroup, already in progress.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

Steven D'Aprano wrote:

  Did you mean: Badger badger Badger badger badger badger Badger badger 
  Mushroom! Mushroom!

 Er... no, I can't parse that. I suffered a Too Much Recursion error about
 the third Badger (I only have a limited runtime stack).

 I asked my missus about this one, she being much better at English grammar
 than I am, and she thinks the badger/mushroom sentence is a wind-up. Is
 she right?

http://www.badgerbadgerbadger.com/ (make sure your speakers are on)

/F



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

Re: Bitching about the documentation...

2005-12-07 Thread skip


Steven I'm always amazed and perplexed at how hot-shot programmers who
Steven would never forget a colon or a brace can be so slap-dash about
Steven using proper punctuation and grammar in English.

That's because there's no equivalent to a compiler or interpreter preventing
them from speaking or writing.

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

Re: Bitching about the documentation...

2005-12-07 Thread Rocco Moretti


One of my favourite examples of obfuscated English is this grammatically
correct sentence:

Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo.
 
 The punctuation is important. 

Reminds me of this old classic:

Insert punctuation  capitalization to make the following a correct and 
coherent (if not a little tourtured).

fred where guido had had had had had had had had had had had a better 
effect on the reader
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

Rocco Moretti wrote:

 Insert punctuation  capitalization to make the following a correct and
 coherent (if not a little tourtured).

 fred where guido had had had had had had had had had had had a better
 effect on the reader

punctuation, including quote marks, I presume?

it's not time to bring out d'ä ä e å, å i åa ä e ö yet, I hope?

/F



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

Re: Bitching about the documentation...

2005-12-07 Thread Aahz

In article [EMAIL PROTECTED],
Rocco Moretti  [EMAIL PROTECTED] wrote:

Reminds me of this old classic:

Insert punctuation  capitalization to make the following a correct and 
coherent (if not a little tourtured).

fred where guido had had had had had had had had had had had a better 
effect on the reader

I'd like to thank my parents, Ayn Rand and God.
-- 
Aahz ([EMAIL PROTECTED])   * http://www.pythoncraft.com/

Don't listen to schmucks on USENET when making legal decisions.  Hire
yourself a competent schmuck.  --USENET schmuck (aka Robert Kern)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

2005-12-07 Thread Michael Spencer

Fredrik Lundh wrote:
 Rocco Moretti wrote:
 
 Insert punctuation  capitalization to make the following a correct and
 coherent (if not a little tourtured).

 fred where guido had had had had had had had had had had had a better
 effect on the reader
 
 punctuation, including quote marks, I presume?
 
 it's not time to bring out d'ä ä e å, å i åa ä e ö yet, I hope?
 
 /F
 
 
 
Allowing quotation, almost anything is possible, e.g.,


Fred! Where Guido had had had, Had had had had had.  Had had had a better 
effect on the reader

or simply

fred, where Guido had had had had had had had had had had, had a better
effect on the reader

M

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

Re: Bitching about the documentation...

2005-12-07 Thread Mike Meyer

Fredrik Lundh [EMAIL PROTECTED] writes:
 Er... no, I can't parse that. I suffered a Too Much Recursion error about
 the third Badger (I only have a limited runtime stack).

I always loved the demonstration that English requires backtracking:
The old man the ship.

 mike
-- 
Mike Meyer [EMAIL PROTECTED]  http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

On Wed, 07 Dec 2005 17:15:03 -0500, Mike Meyer wrote:

 Fredrik Lundh [EMAIL PROTECTED] writes:
 Er... no, I can't parse that. I suffered a Too Much Recursion error about
 the third Badger (I only have a limited runtime stack).
 
 I always loved the demonstration that English requires backtracking:
 The old man the ship.

Linguists call that garden path sentences, because they lead the
reader/listener up the garden path.

Here are some more examples:

The horse raced past the barn fell.

The man who hunts ducks out on weekends.

The cotton clothing is usually made of grows in Mississippi.

The prime number few.

Fat people eat accumulates.

The tycoon sold the offshore oil tracts for a lot of money wanted to kill
JR.



-- 
Steven.

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

Re: Bitching about the documentation...

2005-12-07 Thread Dan Sommers

On Thu, 08 Dec 2005 12:19:13 +1100,
Steven D'Aprano [EMAIL PROTECTED] wrote:

 Linguists call that garden path sentences, because they lead the
 reader/listener up the garden path.

 Here are some more examples:

[ examples snipped ]

And the ever-popular, ever-ambiguous:

Women can fish.

Regards,
Dan

-- 
Dan Sommers
http://www.tombstonezero.net/dan/
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

2005-12-06 Thread skip


 Are you telling us you learned C#, smalltalk, lisp, C, perl,
 whatever, from 1 website only, without looking at any books, without
 spending any money on IDEs or any software?  Cause that's what you're
 asking here.

rurpy For perl and C, yes, that's (close to) what I'm telling you.
rurpy Perl I learned exclusively from the man pages, before WWW.  I
rurpy used it for 10 years before I ever bought a printed book.  C I
rurpy learned exclusively from the KR book.

That's about the same for me, except Perl never stuck.

rurpy I tried to learn Python from the official docs but found it
rurpy impossible.  

I did as well, though the docs as they existed in 1993 or so (that is
pre-Lutz, pre-Beasley).


rurpy I bought Beasley's book (I think this may have predated
rurpy Martelli's book but I don't remember) which I thought quite good
rurpy and which I still turn to before the Python docs in most cases.

Like other free software, you can choose to figure things out yourself (use
the source Luke) or pay someone to help you out.  I'm not using this as an
excuse for poor Python docs.

rurpy That's a very good list and I will save a copy, thanks.  But what
rurpy does it have to do with Python's documentation?

I'm sure you could find similar lists for Perl, C, Ruby, Tcl, Java, C++, C#,
etc.  Does that mean their documentation stinks?  Maybe.  Maybe not.  It
just means a lot of people have somewhat different ways of tackling the same
problem.

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

Re: Bitching about the documentation...

2005-12-06 Thread gene tani


[EMAIL PROTECTED] wrote:
  Are you telling us you learned C#, smalltalk, lisp, C, perl,
  whatever, from 1 website only, without looking at any books, without
  spending any money on IDEs or any software?  Cause that's what you're
  asking here.

 rurpy For perl and C, yes, that's (close to) what I'm telling you.
 rurpy Perl I learned exclusively from the man pages, before WWW.  I
 rurpy used it for 10 years before I ever bought a printed book.  C I
 rurpy learned exclusively from the KR book.

 That's about the same for me, except Perl never stuck.

 rurpy I tried to learn Python from the official docs but found it
 rurpy impossible.

 I did as well, though the docs as they existed in 1993 or so (that is
 pre-Lutz, pre-Beasley).


 rurpy I bought Beasley's book (I think this may have predated
 rurpy Martelli's book but I don't remember) which I thought quite good
 rurpy and which I still turn to before the Python docs in most cases.

 Like other free software, you can choose to figure things out yourself (use
 the source Luke) or pay someone to help you out.  I'm not using this as an
 excuse for poor Python docs.

 rurpy That's a very good list and I will save a copy, thanks.  But what
 rurpy does it have to do with Python's documentation?

 I'm sure you could find similar lists for Perl, C, Ruby, Tcl, Java, C++, C#,
 etc.  Does that mean their documentation stinks?  Maybe.  Maybe not.  It
 just means a lot of people have somewhat different ways of tackling the same
 problem.

 Skip

Skip: good points

orig qvetcher: Well, I won't have time til, maybe early 2007 to debate
the meaning of free software,official docs, is buying KR buying a
book?  In the meantime, use the resources, Luke (i think i've been on
usenet too long... signing out)

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

Re: Bitching about the documentation...

2005-12-06 Thread A.M. Kuchling

On Mon, 05 Dec 2005 20:56:50 GMT, 
Bengt Richter [EMAIL PROTECTED] wrote:
 A little more effort could present the referrer page with clickable
 paragraphs and other elements, to zoom in to what the commenter
 wants to comment on. And an automatic diff could be prepared for
 editors, and the submitted info could go in a structured file for
 automated secure web access by editors to ease review and presumably
 sometimes pretty automatic docs update. Adherence to submission
 guidelines could be enforced somewhat by form checks etc.

A *little* more effort?  This is obviously some strange new
definition of little.  I'd love to see such a system, but it would
be a significant effort to build such a system, and the Python
developers do not have the spare manpower to do it.  It would be a
great volunteer project for someone to undertake, but I don't think
Fred Drake or anyone else has the spare CPU cycles to work on it.

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

Re: Usenet falsehoods (was Re: Bitching about the documentation...)

2005-12-06 Thread skip


 Hmm, I though he explained it:
 
 1) Not using your real name.
 
 2) A yahoo, aol, or hotmail address.
 
 In the ancient and hallowed (by net standards) history of Usenet, both
 of these (particularly the first one) have been pretty good predictors
 of crankness.

aahz I've been on the Net for more than fifteen years, and while this
aahz canard about real names gets trotted out from time to time, it's
aahz quite clear that many many people have been active on the Net
aahz *and* taken seriously using names that aren't what you'd call a
aahz real name.

As the person who raised this particular flag, I will note a few things:

1. Monty Python humor aside, this is generally a serious mailing list
   and newsgroup.  In my experience, most people deal professionally
   with others of like interests by using their real names.

2. While I haven't been to many PyCons, I've been to enough to have met
   many Python folk.  Hell, maybe I've met rurpy and don't even know it.
   Real people have real names.  Using your real name on the net makes
   you less virtual to the people you communicate with.

3. I'm an Internet dinosaur.  I date from the time before l33t speak,
   the Morris worm, spam and Windows increased the need for people to
   hide behind virtual masks and throw away email addresses every few
   months.  At the dawn of time, basically everyone used their real
   names.

It's probably just my misunderstanding about how people use avatars on the
net nowadays, but I still expect professional people to communicate
profesionally.  That includes using real names.

For completeness, though I usually don't here, my full sig:

-- 
Skip Montanaro
Katrina Benefit Concerts: http://www.musi-cal.com/katrina
[EMAIL PROTECTED]
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

2005-12-06 Thread A.M. Kuchling

On Tue, 6 Dec 2005 00:05:38 -0500, 
François Pinard [EMAIL PROTECTED] wrote:
 It's a relatively recent phenomenon that maintainers go berzerk, foaming 
 at the mouth over forms, borders, colors, and various other mania!  :-)

It's largely to ensure that the ideas aren't lost.  E-mail sits around
in an inbox until it gets deliberately deleted or gets lost in a disk
crash or system upgrade gone wrong.  Usenet posts fall out of the news
spool and get buried in Google's archives.

For example, here are the oldest messages in my mailbox:

   1 Mar 24 Whitesell, Ken  (3.5K) [PyCON-Organizers] Feedback from a first-
   2 Mar 28 Martin Maney(1.4K) Improving The Python DB-API interface
   3   T Mar 28 MW Mike Weiner  (1.0K) RE: [Pycon2005-attendees] Found items
   4   + Mar 28 Mark Wittner(0.8K)  *¬
   5   + Mar 29 Anna Ravenscrof (0.9K)   
   6  s+ Mar 28 David Goodger   (1.4K) Re: Q. about Emacs on MacOS
   7   + Apr 04 Neal Norwitz(250K) Re: PyCon treasury question
   8 Apr 28 Thorsten Leemhu (0.7K) python-crypto RIPEMD160 and SHA256 not 64
   9   + May 01 nemir nemiria   (0.4K) regular expression how-to suggestion.
  10 May 07 Brian Hook  (0.3K) pycrypto
  11 May 23 John Lambert (W (3.7K) python howto: regular expressions - issue
  12   T Jun 01 Tim Parkin  (2.5K) pydotorg redesign
  13   T Jun 02 Neal Norwitz(2.3K) Re: [Python-Dev] Vestigial code in thread
  14   + Jun 09 Jacob Rus   (0.5K) python regular expression howto
  15 Jun 17 Zed Lopez   (0.5K) [pct] decrypting a ciphertext with an RSA
  16 Jun 21 Skip Montanaro  (1.3K) Re: [Pydotorg] Python Homepage: possible
  17 Jun 27 Osvaldo Santana (0.7K) [marketing-python] Python Powered in Core
  18   + Jul 09 Martin Kirst(0.3K) pycrypto pre build binaries for windows,
  19 Jul 10 Jeff Rush   (0.9K) [PyCON-Organizers] Two Good Developments
  20 Jul 13 [EMAIL PROTECTED]  (2.5K) Re: [Quixote-users] Quixote 2 Docs
  21   T Jul 15 Nick Jacobson   (0.4K) py3k

#2 from Martin Maney is a suggestion about a web page I have on the DB-API.  
#8 is a pycrypto bug report; I think the bug is fixed now, but would have 
to check.
#9 and #11 are suggestions for the regex HOWTO.
#10, #15, #18 could be suggestions, bug reports, or questions; hope
they're not questions or bugs, because the chance of them being
answered is zero at this point.

You may suggest that I should process my e-mail more promptly.  True,
but that's very hard; there's always newer e-mail coming in.  Do less?
I'd love to, but that doesn't seem to be a viable option.

I could just delete all this mail, but I still have the hope of
someday doing a rewrite pass on, say, the regex howto, going through
all the suggestions and making some changes accordingly.  I am,
however, drifting toward the Linus Torvalds approach of mail handling:
delete messages after six months.  If the message was important,
they'll resend it.  A pity that it means Martin's suggestions, and
Thorsten's bug, and Nemir's suggestion, get discarded.

This is why things need to go into public trackers, or wiki pages.
There, at least their content is available to someone else; if
someday, someone else does a new regex howto, they could use the
suggestions and patches that have accumulated over time.  

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

Re: Usenet falsehoods (was Re: Bitching about the documentation...)

2005-12-06 Thread Aahz

In article [EMAIL PROTECTED],
Grant Edwards  [EMAIL PROTECTED] wrote:
On 2005-12-06, Aahz [EMAIL PROTECTED] wrote:
 In article [EMAIL PROTECTED],
 Grant Edwards  [EMAIL PROTECTED] wrote:

Hmm, I though he explained it:

  1) Not using your real name.

  2) A yahoo, aol, or hotmail address.

In the ancient and hallowed (by net standards) history of Usenet,
both of these (particularly the first one) have been pretty good
predictors of crankness.  The correlation isn't as high as it used
to be, now that hiding behind silly nicknames has apparently become
socially acceptable in other venues (web forums and boards and
whatnot).

 I've been on the Net for more than fifteen years, and while this
 canard about real names gets trotted out from time to time, it's
 quite clear that many many people have been active on the Net *and*
 taken seriously using names that aren't what you'd call a real
 name.  (People named piglet, tigger, and pooh, just for
 example, who were active long before I showed up.  Not to mention
 piranha.)

I didn't said it was 100% reliable, but in most of the technical groups
there sure seemed to be a good correlation beetween screen names and
kooks/trolls.

My point is that I do not think the correlation has changed
significantly over the last fifteen years that I've been observing.
There is still a moderate correlation between screen names and trollish
behavior (just as there was historically); there is still a high enough
chance that people are using a screen name for reasons that have nothing
to do with trollishness that it should never be used as a primary reason
for selecting or rejecting posts from a person (just as it always was
historically).  For that matter, I have no evidence that your name is
Grant Edwards.  If I really cared, I could find people I know in
Minneapolis to look you up...

IOW, it just makes sense to me to skip the whole name issue and simply
respond to people's posts (for some strange reason, I have a vested
interest ;-).
-- 
Aahz ([EMAIL PROTECTED])   * http://www.pythoncraft.com/

Don't listen to schmucks on USENET when making legal decisions.  Hire
yourself a competent schmuck.  --USENET schmuck (aka Robert Kern)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

2005-12-06 Thread François Pinard

[A.M. Kuchling]
On Tue, 6 Dec 2005 00:05:38 -0500, 
   François Pinard [EMAIL PROTECTED] wrote:

 It's a relatively recent phenomenon that maintainers go berzerk, foaming 
 at the mouth over forms, borders, colors, and various other mania!  :-)

 It's largely to ensure that the ideas aren't lost.  E-mail sits around
 in an inbox until it gets deliberately deleted or gets lost in a disk
 crash or system upgrade gone wrong.

Or sorted properly by the recipient, the way he sees best fit, in the 
tracker of his own choice.

I know I'm repeating myself, but my point just does not seem to get 
through.  The maintainer should manage his way as a grown up, instead of 
expecting the world to learn his ways and manage in his place.

 You may suggest that I should process my e-mail more promptly.

No, I'm not suggesting you how to work, no more that I would accept that 
you force me into working your way.  If any of us wants to force the 
other to speak through robots, that one is not far from unspeakable...

 If the message was important, they'll resend it.

This is despising contributions.  If someone sends me a message which 
I find important, I do take means so that message does not get lost, and 
that it will even suvive me for some while.

 This is why things need to go into public trackers, or wiki pages.

Whatever means the maintainer wants to fill his preservation needs, he 
is free to use them.  The problem arises when the maintainer wants 
imposing his own work methods on others.  Let contributors be merely
contributors, and learn how to recognise contributions as such and say 
thank you, instead of trying to turn contributors into maintainers.

-- 
François Pinard   http://pinard.progiciels-bpi.ca
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

2005-12-06 Thread Paul Rubin

François Pinard [EMAIL PROTECTED] writes:
  You may suggest that I should process my e-mail more promptly.
 
 No, I'm not suggesting you how to work, no more that I would accept
 that you force me into working your way.  If any of us wants to force
 the other to speak through robots, that one is not far from
 unspeakable...

In the old days, it was possible to post stuff to Python's sourceforge
pages without logging in.  That was turned off for various reasons
that weren't bogus, but that didn't strike me as overwhelmingly
compelling.  Maybe that could be revisited, at least for the category
of documentation bugs and patches.

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

Re: Bitching about the documentation...


 Gee, I wonder if I typed sort into the search box on the wiki it
 might turn up something useful?  Well, what do you know?
 
 2 results of about 4571 pages. (0.19 seconds)
 
 1. HowTo/Sorting
 2. SortingListsOfDictionaries

rurpy Are we talking about the same Search box (at the top right of the
rurpy wiki page, and labeled search?  Well, yes I did enter sort
rurpy and got (as I said) a long list of archived maillist postings.

Probably.  There are two search buttons, Title and Text.  Always try the
Title search first, as it only searches page titles.  If that is unhelpful,
then try the Text search.  That searches the bodies of the pages.  I
generally never use that search, preferring instead to use Google's
site:wiki.python.org ... restricted search which is going to apply their
page rank algorithms to the hits (and be faster to boot).  I don't know how
hard it would be to modify the wiki's Text button so it executes the
appropriate Google search.  Probably not too hard.  I'll look.

rurpy Well, I'm not totally sure but I think I would be willing to a
rurpy least try contributing something.  A large amount of the time I
rurpy waste when writing Python programs is directly attributable to
rurpy poor documentation.  (To be fair Python is not the only software
rurpy with this problem.)

rurpy But, the standard responce of don't complain, fix it yourself
rurpy is bogus too.  There are plenty of people on this list willing to
rurpy sing python's praises, for balance, there should be people
rurpy willing to openly point out python's flaws.  Documentation is
rurpy certainly one of them.  And I was correcting a posting that
rurpy explicitly said there was exceptionaly good information in that
rurpy Howto.  That was just plain wrong.

Sure, feel free to point of flaws.  Just don't let that be the only way you
contribute.  Over time the value of your criticism (valid or not) will be
discounted.

The preferred way to correct problems with the documentation is to submit a
bug report to SourceForge.  Many of the active developers (including those
who do write most of documentation) don't necessarily track c.l.py closely,
so postings here often will get lost because people can't attend to them
immediately.

The problem with marching in here and saying fix the docs is that you are
an unknown quantity (I certainly don't recognize your email address and as
far as I've seen you never sign your posts.  I don't believe I've ever seen
contributions from you either.  (Can't double-check right now because
SourceForget is basically unresponsive.)  The combination makes you look
suspiciously like a troll.  I doubt that's the case.  Troll detectors are
notorious for generating false positives.  Still, my threat assessment level
got raised.

Operating under the rurpy's-not-a-troll assumption, your posts suggest to me
that you don't understand how Python is developed.  Behind the scenes lots
of documentation *does* get written.  In my experience it hass generally not
been written by people who whine, fix the docs.  In short, there seems to
be no shortage of people willing to castigate the Python developers for
poor documentation.  There does appear to be a shortage of people willing to
actually roll up their sleeves and help.

The other thing to remember is that most of the people who wind up writing
the documentation don't personally need most of the documentation they
write.  After all, they are generally the authors of code itself and are
thus the experts in its use.  It's tough to put yourself in the shoes of a
novice, so it's tough to write documentation that would be helpful for new
users.  It's extremely helpful if new users submit documentation patches as
they figure things out.  It's generally unnecessary to write large tomes.
Often all that's needed is a few sentences or an example or two.

Skip

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

Re: Bitching about the documentation...

2005-12-05 Thread bonono


[EMAIL PROTECTED] wrote:
 Sure, feel free to point of flaws.  Just don't let that be the only way you
 contribute.  Over time the value of your criticism (valid or not) will be
 discounted.
 
That is quite interesting, if it is true.

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

Re: Bitching about the documentation...


 Sure, feel free to point of flaws.  Just don't let that be the only
 way you contribute.  Over time the value of your criticism (valid or
 not) will be discounted.

bonono That is quite interesting, if it is true.

Let me rephrase.  The discounting I referred to is largely subconcious.
When it is concious it's a roll of the eyes or a thought like, Oh that
whiner again.  I don't have time for this right now.  And the 'd' key gets
hit.  I didn't mean to imply some sort of smoke-filled backroom where the
developers decide whose inputs to listen to.

Everybody applies such filters whether they think about it or not.  Here are
a couple of mine:

Xah Lee?  Hit the 'd' key.

Tim Peters? Read it no matter what the subject says.

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

Re: Bitching about the documentation...

 It's tough to put yourself in the shoes of a
novice, so it's tough to write documentation that would be helpful for
new
users.  It's extremely helpful if new users submit documentation
patches as
they figure things out.  It's generally unnecessary to write large
tomes.
Often all that's needed is a few sentences or an example or two. 

Yes, well, regardless of your beef with the person who complained about
documentation, I respectfully submit that it is not so easy to help out
with documentation. I'm a professional writer and author with a keen
interest in open source, but the moment you look to contribute or try
to help with the documentation you are asked to learn LaTex or DocBook,
which, I'm sorry, I am not going to do.  Authors and writers are
usually drawn to open source software by their love of plain text.
Even veteran Linux users have a lot of trouble with LaTex, so the
writers, who perhaps would be willing to help with writing in exchange
for help with programming, are unable to do so without learning yet
another arcane and foreign mark-up language, which frankly won't be
useful in any other writing endeavor. How about a compromise, like
having documents submitted in html or some other system that is more
cross platform than LaTex?

bs

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

Re: Bitching about the documentation...

2005-12-05 Thread Aahz

In article [EMAIL PROTECTED],
 [EMAIL PROTECTED] wrote:

Tim Peters? Read it no matter what the subject says.

A-men!
-- 
Aahz ([EMAIL PROTECTED])   * http://www.pythoncraft.com/

Don't listen to schmucks on USENET when making legal decisions.  Hire
yourself a competent schmuck.  --USENET schmuck (aka Robert Kern)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

2005-12-05 Thread Aahz

In article [EMAIL PROTECTED],
BartlebyScrivener [EMAIL PROTECTED] wrote:

Yes, well, regardless of your beef with the person who complained about
documentation, I respectfully submit that it is not so easy to help out
with documentation. I'm a professional writer and author with a keen
interest in open source, but the moment you look to contribute or try
to help with the documentation you are asked to learn LaTex or DocBook,
which, I'm sorry, I am not going to do.

This is not true.  You are welcome to submit plain text patches; reST
patches are even better.  There has been a lot of confusion on this point
in the past (to which I responded by submitting a bug report and getting
the docs about submitting patches changed).  Can you point out where
you're getting this impression from so we can make further improvements
to the process?  Or do I (and others) simply need to keep repeating this
point endlessly?
-- 
Aahz ([EMAIL PROTECTED])   * http://www.pythoncraft.com/

Don't listen to schmucks on USENET when making legal decisions.  Hire
yourself a competent schmuck.  --USENET schmuck (aka Robert Kern)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

Go to Python.org

Click on DEVELOPERS

The lead sentence says:

Contributors and potential contributors should read Documenting Python,
which describes in details the conventions and markup used in creating
and maintaining the Python documentation. The CVS trunk version is the
recommended version for contributors, regardless of which Python branch
is being modified.

The link takes you straight to a primer on LaTex.

Did I miss something?

bs

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

Re: Bitching about the documentation...

2005-12-05 Thread Scott David Daniels

BartlebyScrivener wrote:
...a reasonable description of why he felt he had to learn LaTeX ...

 Did I miss something?

At the bottom of most pages of the python docs is a link to:

 About the Python Documentation

where it says (among other things):
 If you find specific errors in this document, please report the bug
at the Python Bug Tracker at SourceForge. If you are able to provide
suggested text, either to replace existing incorrect or unclear
material, or additional text to supplement what's already available,
we'd appreciate the contribution. There's no need to worry about text
markup; our documentation team will gladly take care of that

-- 
-Scott David Daniels
[EMAIL PROTECTED]
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

Thank you. I shall try that the next time I see something in the
documentation for beginners. Generally the Python docs are quite good,
in my opinion. I was merely taking issue with the poster who suggested
that Python novices and nonprogrammers should complain less and
contribute more. It's not immediately apparent how to contribute. And
if you go looking via the main page you end up in a LaTex tutorial.

bs

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

Re: Bitching about the documentation...

2005-12-05 Thread Bengt Richter

On 5 Dec 2005 10:53:36 -0800, [EMAIL PROTECTED] (Aahz) wrote:

In article [EMAIL PROTECTED],
BartlebyScrivener [EMAIL PROTECTED] wrote:

Yes, well, regardless of your beef with the person who complained about
documentation, I respectfully submit that it is not so easy to help out
with documentation. I'm a professional writer and author with a keen
interest in open source, but the moment you look to contribute or try
to help with the documentation you are asked to learn LaTex or DocBook,
which, I'm sorry, I am not going to do.

This is not true.  You are welcome to submit plain text patches; reST
patches are even better.  There has been a lot of confusion on this point
in the past (to which I responded by submitting a bug report and getting
the docs about submitting patches changed).  Can you point out where
you're getting this impression from so we can make further improvements
to the process?  Or do I (and others) simply need to keep repeating this
point endlessly?
With all due respect, ISTM submission of comments and additions to 
docs.python.org
web pages could be made easier. There is a link at the bottom of many/most doc 
pages (all?) to

http://docs.python.org/lib/about.html

ISTM it would be easy to have an addditional clickable submit-comment link to 
e.g. a generated
framed page with the referrer doc page on top and a comment text box at the 
bottom (or whatever
looks good, with scrolling  for view of orig doc page), to make it easy to 
comment. A few check boxes
could categorize as to spelling/typo corrections vs adding helpful links or 
cross references,
vs wiki references, vs just griping, vs adding whole sections, etc.

A little more effort could present the referrer page with clickable paragraphs 
and other elements,
to zoom in to what the commenter wants to comment on. And an automatic diff 
could be prepared for editors,
and the submitted info could go in a structured file for automated secure web 
access by editors to ease review
and presumably sometimes pretty automatic docs update. Adherence to submission 
guidelines could be
enforced somewhat by form checks etc.

For general volunteering, a page could be generated automatically showing 
counts of failed search
subjects. Search could be modified with a form to log a gripe/suggestion about 
a failed search, that would
also be accessible. The failed search-term count display could also show a 
count of associated
comments.

We could agree on newspost tag-lines to enable automatic harvesting of gripes, 
topic suggestions, links,
etc from c.l.p newslist archives. E.g.,

[BeginPythonDocsHarvest]
(automatically harvestable info to go here, format TBD, but maybe
 rfc2822 could be looked for, or XML or rest etc?)
[EndPythonDocsHarvest]


E.g, to add a link to this (the one you are reading) post/thread to a database
of ref links for various doc pages that would ultimately show up as a single
clickable [refs] item at the bottom of pages that have refs, one could
tag a post with something like

[BeginPythonDocsHarvest]
LinkToThisThread: http://docs.python.org/about.html
[EndPythonDocsHarvest]

I guess I better stop ;-)

Regards,
Bengt Richter
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

2005-12-05 Thread nick

BartlebyScrivener [EMAIL PROTECTED] writes:

 Go to Python.org

 Click on DEVELOPERS

 The lead sentence says:

 Contributors and potential contributors should read Documenting Python,
 which describes in details the conventions and markup used in creating
 and maintaining the Python documentation. The CVS trunk version is the
 recommended version for contributors, regardless of which Python branch
 is being modified.

 The link takes you straight to a primer on LaTex.

 Did I miss something?

The Documenting Python link takes you to a page that starts like this
- NB. the last sentence of the abstract:


Documenting Python

Fred L. Drake, Jr.

PythonLabs
Email: [EMAIL PROTECTED]

Release 2.5a0
August 9, 2005

Abstract:

The Python language has a substantial body of documentation, much of
it contributed by various authors. The markup used for the Python
documentation is based on LaTeX and requires a significant set of
macros written specifically for documenting Python. This document
describes the macros introduced to support Python documentation and
how they should be used to support a wide range of output formats.

This document describes the document classes and special markup used
in the Python documentation. Authors may use this guide, in
conjunction with the template files provided with the distribution, to
create or maintain whole documents or sections.

If you're interested in contributing to Python's documentation,
there's no need to learn LaTeX if you're not so inclined; plain text
contributions are more than welcome as well.



-- 
nick  (nicholas dot dokos at hp dot com)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

2005-12-05 Thread John J. Lee

BartlebyScrivener [EMAIL PROTECTED] writes:

 Thank you. I shall try that the next time I see something in the
 documentation for beginners. Generally the Python docs are quite good,
 in my opinion. I was merely taking issue with the poster who suggested
 that Python novices and nonprogrammers should complain less and
 contribute more. It's not immediately apparent how to contribute. And
 if you go looking via the main page you end up in a LaTex tutorial.

Just by-the-way: Actually the Python docs use a really restricted
range of LaTeX commands, so you really need know *nothing* about LaTeX
even if you *do* go to the trouble of supplying LaTeX markup.  Just
follow what you see in the files in eg. python/trunk/Doc/lib/lib*.tex
(if you scan through the list of markup available in the 'Documenting
Python' manual, even better), and be sure to warn of the fact that
you're a LaTeX newbie when uploading patches so committers know what
they're getting.

(My advice is don't try to *compile* the docs unless you're ready for
some pain, though -- last time I looked it was quite unpleasant to get
it working.)

Also, note that Python is now in SVN, no longer in CVS:

http://svn.python.org/view/python/trunk/Doc/lib/
http://svn.python.org/projects/python/trunk/Doc/lib/
http://www.python.org/dev/devfaq.html#subversion-svn

http://docs.python.org/doc/doc.html


John

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

Re: Bitching about the documentation...


Tony Meyer [EMAIL PROTECTED] wrote:
  But, the standard responce of don't complain, fix it yourself is
  bogus too.  There are plenty of people on this list willing to sing
  python's
  praises, for balance, there should be people willing to openly
  point out
  python's flaws.

 This makes no sense.  If you want to complain about Python, try a
 Perl list.  Why would a list dedicated to discussion about/help with
 a language need complaints about the language?

1. So group readers might have advance warning of problem
  they may run into.
2. To give potential adopters of Python a more even handed view
  of the language.
2. So developers will have a better idea of the problems the
  user base is actually having with Python.
3. To motivate those who are looking for a way to contribute.
3. So that people who want to express an honest opinion in an
  open forum won't feel intimidated.
I could probably think of more but I'm tired of typing.

I propose a couple additions the Zen document:
  Reality beats fantasy.
  Open discussion is better that propaganda.

 You might want to consider the difference between complaining and
 constructive criticism and suggestions, and which are likely to get
 better responses.

I agree within limits, but sometimes constructive criticism means
play by our rules which for me is outside the limits.  Also
non-constructive
criticism while not as valuable, is not worthless either.

  Documentation is certainly one of them.

 FWIW, I have found Python's documentation to generally be excellent.

FWIW I find Python's docs to be OK at best, with some horrible
parts, and a lot of mediochre to poor parts.

1. I have seen recommendations here to use new-style classes.
I believe classes are at the core of Python, the entire language
is built around and rests on them.  Yet, unless I missed it,
new style classes are almost completely undocumented in
the Language Reference Manual.  This alone is sufficient
to condemn the documentation.

2.Section 2 of the Library Reference should clearly be in the
Language Reference manual.

3.There are way to few examples in the docs.

4.There are way to few cross references in the docs (for example
the datetime module doesn't even mention the existence of the
time module.) [I double checked before posting and see this is
no longer true, but I think it is still true in many other cases. ]

5.Forward refernces (mention of things explained or defined
later in the manual) are seldom identified as such.  They should
be a link to the appropriate part of the manual.

6.There is often no notational distinction for terms used in a
general sense and a python specific technical sense leading
to confusion.

7.The writing is often too terse.  (To parapharse, it should be as
terse as possible but no terser.  I think it often violates the
that last clause.)

8.There is critical missing info.  (I lost many hours once because
the process module (or popen? I forgot) failed to document it
didn't do unicode.)

9.Many other small details, e.g is it neccesary for the one of the
most frequently used datatypes (string) to not appear in the
table of contents?  (That's not retorical, I really don't know.
Maybe it is, but if things could be arranged to that it did, it would
be better.)

  And I was correcting a posting that explicitly said there was
  exceptionaly
  good information in that Howto.  That was just plain wrong.

 It is exceptionally good information.  The version that was at that
 link is somewhat dated (but still excellent for anyone using older
 versions of Python, or for those that need to remain compatible with
 older versions, and there are a lot of those people around), but the
 updated version is also excellent.  I'm sure amk will either update
 his page to point to the new one or update the content at some point.

No, it is not exceptionally good information.  It is outdated
information,
it does not say it is outdated, and it will lead to poor practice when
used
in the version of Python that it documents.  That clearly makes it not
good.

 The point is that you're much more likely to improve things if you
 politely point out a problem and suggest a solution than simply make
 a complaint.

I did.  As for my original responce I think the suggestion was clear
if implicit: stop referring to outdated documentation as a treasure.
The suggestion in my update the damn docs comment was quite
explicit I think.

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

Re: Bitching about the documentation...


[EMAIL PROTECTED] wrote in message
news:[EMAIL PROTECTED]
--snip--
 rurpy Well, I'm not totally sure but I think I would be willing to a
 rurpy least try contributing something.  A large amount of the time I
 rurpy waste when writing Python programs is directly attributable to
 rurpy poor documentation.  (To be fair Python is not the only software
 rurpy with this problem.)

 rurpy But, the standard responce of don't complain, fix it yourself
 rurpy is bogus too.  There are plenty of people on this list willing to
 rurpy sing python's praises, for balance, there should be people
 rurpy willing to openly point out python's flaws.  Documentation is
 rurpy certainly one of them.  And I was correcting a posting that
 rurpy explicitly said there was exceptionaly good information in that
 rurpy Howto.  That was just plain wrong.

 Sure, feel free to point of flaws.  Just don't let that be the only way you
 contribute.  Over time the value of your criticism (valid or not) will be
 discounted.

 The preferred way to correct problems with the documentation is to submit a
 bug report to SourceForge.  Many of the active developers (including those
 who do write most of documentation) don't necessarily track c.l.py closely,
 so postings here often will get lost because people can't attend to them
 immediately.

 The problem with marching in here and saying fix the docs is that you are
 an unknown quantity (I certainly don't recognize your email address and as
 far as I've seen you never sign your posts.

I don't believe my name, etnic heritage, gender, age, employer or
school, or part of the world I live in, have any bearing on the
contents
of my postings.

 I don't believe I've ever seen
 contributions from you either.  (Can't double-check right now because
 SourceForget is basically unresponsive.)

I try to contribute on c.l.p when I can but those times are rare.  I
freely
admit I am a python newbie so in most cases it is more appropriate
for me to read answers than to supply them.  And traffic is so high it
is rare when I see a question I can answer, that someone hasn't
already answered better.

 The combination makes you look
 suspiciously like a troll.  I doubt that's the case.  Troll detectors are
 notorious for generating false positives.  Still, my threat assessment level
 got raised.

I would say I am more than 90% serious and less than 10%
troll. :-)  Perhaps the reason your detector went off is because
I have posted some Politically Incorrect opinions in the same
absolutist, dogmatic, style used by many PC posters?  Sorry,
life is short and I am not interested in sugar coating anything.

 Operating under the rurpy's-not-a-troll assumption, your posts suggest to me
 that you don't understand how Python is developed.  Behind the scenes lots
 of documentation *does* get written.  In my experience it hass generally not
 been written by people who whine, fix the docs.  In short, there seems to
 be no shortage of people willing to castigate the Python developers for
 poor documentation.  There does appear to be a shortage of people willing to
 actually roll up their sleeves and help.

Well, I guess I would be willing to consider trying to help.  (I say
try
because I am lousy at technical writing so my help may not be very
helpful.)  One thing that's not clear to me is exactly what audience
are
the docs aimed at?  If the powers-that-be have declared that the Lang
Ref. Manual is going to be a minimalist reference with an audience that

already has a high level knowledge of Python, there is no point in my
contributing because:
1. I can't write at that level.
2. I have no interest in a manual positioned at that level.
If the audience is some lower level (e.g. programmers with
some familiarity with OO but no Python knowledge) then I
would be much more motivated to help.  (Note that I am NOT
talking about turning the Lang.Ref.Man into a tutorial!!!)

 The other thing to remember is that most of the people who wind up writing
 the documentation don't personally need most of the documentation they
 write.  After all, they are generally the authors of code itself and are
 thus the experts in its use.  It's tough to put yourself in the shoes of a
 novice, so it's tough to write documentation that would be helpful for new
 users.  It's extremely helpful if new users submit documentation patches as
 they figure things out.  It's generally unnecessary to write large tomes.
 Often all that's needed is a few sentences or an example or two.

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

Re: Bitching about the documentation...

2005-12-05 Thread Fredrik Lundh

[EMAIL PROTECTED] wrote:

  The problem with marching in here and saying fix the docs is that you are
  an unknown quantity (I certainly don't recognize your email address and as
  far as I've seen you never sign your posts.

 I don't believe my name, etnic heritage, gender, age, employer or
 school, or part of the world I live in, have any bearing on the
 contents of my postings.

perhaps not, but it's not what you think that's important here.  and I sure
cannot find anything in your posts that I haven't seen before.  this is use-
net, after all; there's no shortage of anonymous posters hiding behind silly
nicknames who think they're somehow smarter than everyone else...

(and frankly, nobody takes people with hotmail.com or yahoo.com addresses
seriously ;-)

/F



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

Re: Bitching about the documentation...


Fredrik Lundh wrote:
 [EMAIL PROTECTED] wrote:

  I don't believe my name, etnic heritage, gender, age, employer or
  school, or part of the world I live in, have any bearing on the
  contents of my postings.

 perhaps not, but it's not what you think that's important here.  and I sure
 cannot find anything in your posts that I haven't seen before.  this is use-
 net, after all; there's no shortage of anonymous posters hiding behind silly
 nicknames who think they're somehow smarter than everyone else...

I don't know what I posted that gave you that false idea about me.

 (and frankly, nobody takes people with hotmail.com or yahoo.com addresses
 seriously ;-)

You can judge people using whatever criteria you want, of course ;-)

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

Re: Bitching about the documentation...

 bs == BartlebyScrivener  [EMAIL PROTECTED] writes:

bs I'm a professional writer and author with a keen interest in open
bs source, but the moment you look to contribute or try to help with
bs the documentation you are asked to learn LaTex or DocBook, which,
bs I'm sorry, I am not going to do.

Let me repeat this for the umpteenth time: You do not have to learn LaTeX to
contribute to docs.  Submit plain text.  One of us with some LaTeX knowledge
will do the markup.  Content is the hard part.  Markup is nothing, so don't
let it be a barrier for you.

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

Re: Bitching about the documentation...

Let me repeat this for the umpteenth time: You do not have to learn LaTeX to
contribute to docs. 

Noted. And thanks again to all who responded. The tone of this whole
thing is really antagonistic in parts, which is unfortunate. I'll offer
my services through the proper channels, because I appreciate the
generosity of those who share their programming knowledge. In the
meantime, I think perhaps Bengt Richter's post is probably the most
constructive.

Meanwhile, if you have to keep repeating things for the umpteenth time
then it MIGHT be because the way it is laid out or organized is making
it difficult for the person seeking to VOLUNTEER to help. And we come
full circle to documentation.

Why do people continue getting the impression that they need to learn
LaTex to submit documentation?  A writer would look to his text. A
programmer would probably just accuse his audience of being obtuse.

rpd
www.dooling.com

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

Re: Bitching about the documentation...

2005-12-05 Thread Grant Edwards

On 2005-12-05, [EMAIL PROTECTED] [EMAIL PROTECTED] wrote:

 I don't believe my name, etnic heritage, gender, age, employer
 or school, or part of the world I live in, have any bearing on
 the contents of my postings.

 perhaps not, but it's not what you think that's important
 here.  and I sure cannot find anything in your posts that I
 haven't seen before.  this is usenet, after all; there's no
 shortage of anonymous posters hiding behind silly nicknames
 who think they're somehow smarter than everyone else...

 I don't know what I posted that gave you that false idea about
 me.

Hmm, I though he explained it:

  1) Not using your real name.

  2) A yahoo, aol, or hotmail address.

In the ancient and hallowed (by net standards) history of
Usenet, both of these (particularly the first one) have been
pretty good predictors of crankness.  The correlation isn't as
high as it used to be, now that hiding behind silly nicknames
has apparently become socially acceptable in other venues (web
forums and boards and whatnot).
  
 (and frankly, nobody takes people with hotmail.com or
 yahoo.com addresses seriously ;-)

 You can judge people using whatever criteria you want, of
 course ;-)

He's just trying to warn you that, on Usenet, by not using your
real name you start out with negative credibility points in the
minds of most of the old-school Usenet denizens -- and having a
yahoo address subtracts a few more points.  That just means
you're going to have to work a bit to get back up to the same
point that somebody with a real name and a real ISP would
start at.

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

Re: Bitching about the documentation...

2005-12-05 Thread Fredrik Lundh

Grant Edwards wrote:

 The correlation isn't as high as it used to be, now that hiding
 behind silly nicknames has apparently become socially acceptable
 in other venues (web forums and boards and whatnot).

on the other hand, hanging out on web forums and boards is in it-
self a good predictor.

(if you read enough blogs, you'll notice that you can use the same
filters for blog commenters as well; people behave in pretty much
the same way, no matter what net protocol they're using...)

 old-school Usenet denizens

if you've been on the Usenet long enough, you've seen it all.

/F



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

Re: Bitching about the documentation...

2005-12-05 Thread gene tani

[EMAIL PROTECTED] wrote:
[EMAIL PROTECTED] wrote:

Gee, I wonder if I typed sort into the search box on the wiki it might
turn up something useful? Well, what do you know?

2 results of about 4571 pages. (0.19 seconds)

1. HowTo/Sorting
2. SortingListsOfDictionaries

Are we talking about the same Search box (at the top right of the
wiki page, and labeled search? Well, yes I did enter sort and
got (as I said) a long list of archived maillist postings.

Is it as good as Google (site:wiki.python.org sort)? Unlikely, but it
works fairly well. Granted, wikis are a different way of organizing content
than static documentation with their nicely organized chapters, sections and
indexes, but most of us around here are software engineer types, not tech
writers, and since we're not paid to do any of this, we get to do anything
we want. Most of us choose not to write documentation in our spare time.
Go figure. If documentation's your thing, be my guest. Write new
documentation, submit patches for existing documentation, rewrite it in
Word. I don't care. Do whatever floats your boat. Just don't show up and
bitch about the documentation if you're not willing to help.

Well, I'm not totally sure but I think I would be willing to a least
try
contributing something. A large amount of the time I waste when
writing Python programs is directly attributable to poor documentation.
(To be fair Python is not the only software with this problem.)

But, the standard responce of don't complain, fix it yourself is
bogus
too. There are plenty of people on this list willing to sing python's
praises,
for balance, there should be people willing to openly point out
python's
flaws. Documentation is certainly one of them. And I was correcting a
posting that explicitly said there was exceptionaly good information in
that Howto. That was just plain wrong.

Oh, did I mention that there's an Edit link at the top of almost every page
on the wiki and that creating new pages is pretty simple? (Try searching
the wiki for WikiCourse.) Contributing new content to the existing more
static documentation isn't all that hard either.

As I said, I think wiki's suck. On almost every one I find the
information
disorganised, very spotty in coverage, extremely variable is qualilty
of writing, and often seeming like a conversation walked into in the
middle of. I still haven't figured out how to get to the Python wiki's
howto's by navigating from the front page. IMO wikis are best used
to collect information for later editing and inclusion into more formal
documentation. (That's a little stronger than my actual opinion but
it's too late right now more me to express it any better.)

If you prefer the latest documentation, bookmark this page:

http://www.python.org/dev/doc/devel/index.html

Thanks I will keep that in mind. But the obvious risk is that it
will refer to language features and changes not in the current
version.

That's updated every few months, more frequently as new releases approach.

Well, the docs are what they are, I can find what I need. Are you
telling us you learned C#, smalltalk, lisp, C, perl, whatever, from 1
website only, without looking at any books, without spending any money
on IDEs or any software? Cause that's what you're asking here.

So either spend a little money, buy the Nutshell and Cookbook, (or,
look at dozens of books, and many excellent ones:
http://www.amazon.com/exec/obidos/tg/browse/-/285856/ref=dp_brlad_entry/103-3311503-6360648

or spend some time, look at the 2 complete intro books published on the

web, there's also:

http://awaretek.com/tutorials.html
http://www.vex.net/parnassus/
http://directory.google.com/Top/Computers/Programming/Languages/Python/Modules/
http://cheeseshop.python.org/
http://the.taoofmac.com/space/Python/Grimoire
http://dmoz.org/Computers/Programming/Languages/Python/Modules/

http://aspn.activestate.com/ASPN/Cookbook/Python
http://python.codezoo.com/
http://sourceforge.net/softwaremap/trove_list.php?form_cat=178xdiscrim=178

Here's some FAQ/gotchas:
http://www.ferg.org/projects/python_gotchas.html
http://zephyrfalcon.org/labs/python_pitfalls.html
http://zephyrfalcon.org/labs/beginners_mistakes.html
http://www.python.org/doc/faq/
http://diveintopython.org/appendix/abstracts.html
http://www.onlamp.com/pub/a/python/2004/02/05/learn_python.html
http://www.norvig.com/python-iaq.html
http://www.faqts.com/knowledge_base/index.phtml/fid/245
http://amk.ca/python/writing/warts

So i don't think you ca really say the lang spec, the VM and the dev
environment in general are poorly documented.

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

Re: Bitching about the documentation...

2005-12-05 Thread Steve Holden

BartlebyScrivener wrote:
Let me repeat this for the umpteenth time: You do not have to learn LaTeX to
 
 contribute to docs. 
 
 Noted. And thanks again to all who responded. The tone of this whole
 thing is really antagonistic in parts, which is unfortunate. I'll offer
 my services through the proper channels, because I appreciate the
 generosity of those who share their programming knowledge. In the
 meantime, I think perhaps Bengt Richter's post is probably the most
 constructive.
 
 Meanwhile, if you have to keep repeating things for the umpteenth time
 then it MIGHT be because the way it is laid out or organized is making
 it difficult for the person seeking to VOLUNTEER to help. And we come
 full circle to documentation.
 
 Why do people continue getting the impression that they need to learn
 LaTex to submit documentation?  A writer would look to his text. A
 programmer would probably just accuse his audience of being obtuse.
 
 rpd
 www.dooling.com
 

I'd like to suggest that since you aren't by any means the first person 
to form the impression that Latex knowledge is required, we probably 
*should* be making more effort to publicise the acceptability of plain 
text patches to the documentation.

Thanks for persisting long enough to get to this point: it would be 
unfortunate to lose potential contributions simply because of an 
inadequacy in the documentation. We definitely need to lose the 
antagonistic tone, but I do know from experience that there are whiners 
who, unlike you, aren't really prepared to do much to help.

As a small start I've edited

   http://www.python.org/dev/doc/

and if you can think of other changes that will get Fred and Skip more 
help on the documentation I'll try to make those too.

regards
  Steve
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006  www.python.org/pycon/

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

Re: Bitching about the documentation...

2005-12-05 Thread François Pinard

[EMAIL PROTECTED]

 Let me repeat this for the umpteenth time: You do not have to learn 
 LaTeX to contribute to docs.  Submit plain text.  One of us with some 
 LaTeX knowledge will do the markup.  Content is the hard part.  Markup 
 is nothing, so don't let it be a barrier for you.

More than LaTeX, the main frozener is when people in charge tell you to 
use bug trackers to speak to them.

This is like standing up with someone, having a conversation, and your 
partner suddenly tells you: If you want to speak to me, please study 
this form, carefully read the small print, fill it properly and send the 
yellow copy at this address.  Surprised, you ask: Why should I do 
that?, and he replies: I might forget our conversation if you don't 
fill a form for me.  Even more suprіsed, you say:  Gosh, can't you 
manage your own notes yourself, as you see them fit?  Most grown up 
people are able to take care of themselves, you know.  I just do not 
like filling these forms!  Besides, _my_ time is quite precious.

Astonished, you just cannot believe what you hear.  Life is so short, 
you think, why one would ought to stand with such guys?  As the room is 
full of other interesting people, you happily move on towards them.

-- 
François Pinard   http://pinard.progiciels-bpi.ca
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

François Pinard [EMAIL PROTECTED] writes:
  Let me repeat this for the umpteenth time: You do not have to learn
  LaTeX to contribute to docs.  Submit plain text.  One of us with
  some LaTeX knowledge will do the markup.  Content is the hard part.
  Markup is nothing, so don't let it be a barrier for you.
 
 More than LaTeX, the main frozener is when people in charge tell you
 to use bug trackers to speak to them.

More than latex and bug trackers, the main obstacle is that people
wanting better docs want them for the precise reason that the existing
docs don't make it clear what the code does.  Writing a good doc patch
(and the patches needed are often sweeping rewrites) requires
studying and understanding the code being documented, and the
application area that the code tries to implement.  Maybe it also
requires studying relevant standards that the code implements (to note
gaps in the implementation), comparing the implementation to other
implementations in other languages, etc.  For example, writing a good
doc patch for urllib2 would mean checking RFC 2616(?) against the
urllib2 code to see what parts of the RFC got implemented and what
parts didn't.  It might also mean comparing urllib2 with other
libraries like LWP (Perl) or whatever the equivalent is in Java.

By the time the requester/patch writer gets through studying the code
to figure out what it does, maybe s/he has answered his/her own
questions and doesn't need docs any more.  The person best qualified
to know what the code does is the code author, who could answer all
the questions immediately.

The solution is clear: the distro maintainers should require that all
code contributions must come with good docs.  When a code submission
comes in, the distro maintainers should critically review the
accompanying docs, note any shortcomings and constructively ask for
improvements from the contributor until the docs are good.  The distro
committers are all very skilled and experienced people.  So there's a
certain amount of mentoring going on whenever a committer works with a
contributor to accept a code patch.  By communicating what it takes to
bring documentation up to snuff, the committers can share their wisdom
with contributors and thereby raise the quality standard of not just
the distro, but also of the whole contributor community.  Passing
skills on to others is after all what being a community is about.
Many of us who have acquired any skill at putting docs together,
acquired them in precisely this fashion, and should try to pass them on.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...


François More than LaTeX, the main frozener is when people in charge
François tell you to use bug trackers to speak to them.

Understood.  I wish either a) SourceForge supported email interaction with
their trackers or b) someone would finish off the Roundup issue tracker
http://roundup.sourceforge.net/ for python.org.  I doubt if anyone here
can do anything about the first barrier, but if you know something about
Roundup (or would like to learn about it) and would like to contribute
something non-documentational that would really have a direct, positive
impact on the Python community, send a note to [EMAIL PROTECTED]

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

Re: Bitching about the documentation...


Paul For example, writing a good doc patch for urllib2 would mean
Paul checking RFC 2616(?) against the urllib2 code to see what parts of
Paul the RFC got implemented and what parts didn't.  It might also mean
Paul comparing urllib2 with other libraries like LWP (Perl) or whatever
Paul the equivalent is in Java.

Sounds like a subject matter expert is needed here, not a garden variety
tech writer or Python programmer.  Documentation of esoteric stuff requires,
well, esoteric knowledge.

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

Re: Bitching about the documentation...

2005-12-05 Thread Ben Finney

François Pinard [EMAIL PROTECTED] wrote:
 More than LaTeX, the main frozener is when people in charge tell you
 to use bug trackers to speak to them.
 
 This is like standing up with someone, having a conversation,

... in which you informally ask them to do something...

 and your 
 partner suddenly tells you: If you want to speak to me,

... to give specific suggestions for improvement...

 please study this form, carefully read the small print, fill it
 properly and send the yellow copy at this address.

... so that it can go with all the other requests I get at various
times from various people.

 Surprised, you ask: Why should I do that?, and he replies: I
 might forget our conversation if you don't fill a form for me.
 Even more suprіsed, you say:  Gosh, can't you manage your own notes
 yourself, as you see them fit?  Most grown up people are able to
 take care of themselves, you know.  I just do not like filling
 these forms!  Besides, _my_ time is quite precious.
 
 Astonished, you just cannot believe what you hear.  Life is so
 short, you think, why one would ought to stand with such guys?

Perhaps because you have asked them to do something that benefits you,
and they receive multiple requests of that type from many different
people?

 As the room is full of other interesting people, you happily move on
 towards them.

If you just want to have conversations, talk to whomever you like.

If you want someone specific to voluntarily do something, yes, you'll
have to meet them halfway by helping them help you.

-- 
 \  I put instant coffee in a microwave oven and almost went back |
  `\   in time.  -- Steven Wright |
_o__)  |
Ben Finney
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

The solution is clear: the distro maintainers should require that all
code contributions must come with good docs.  When a code submission
comes in, the distro maintainers should critically review the
accompanying docs, note any shortcomings and constructively ask for
improvements from the contributor until the docs are good.  

Well, that might be asking a bit too much of the programmers, who
perhaps don't exactly enjoy mucking about in the lowlands of English
grammar and syntax. All I was saying is you should court writers and
mid-level programmers with writing skills (not saying I'M mid-level,
I'm still learning) to HELP with creating good documentation. When a
writer thinks about helping they go to a page where they are greeted by
a bug report menu or CSV notices or some such. That's why most of your
really good stuff for beginners is on separately created web pages,
where writers simply take matters into their own hands. Also fine, not
saying it should be different.

Again, taking something like Bengt Richter's suggestion as just one
example. To me the module docs are almost incomprehensible without good
examples. Why not have a button where people could submit nice SHORT
examples illustrating otherwise pure theoretical code and geek-speak.
Of course, the editors would decide in a survival-of-the-fittest
contest which example gets used, but the point is you'd get good free
examples this way.

In general, I'd be happy to help a programmer with writing if it meant
I would learn programming along the way. It should be that easy. 

rd

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

Re: Bitching about the documentation...

[EMAIL PROTECTED] writes:
 Sounds like a subject matter expert is needed here, not a garden variety
 tech writer or Python programmer.  Documentation of esoteric stuff requires,
 well, esoteric knowledge.

Yes, that's what I mean; coding a library module for an esoteric
function requires that same esoteric knowledge, and those are the
modules for which the docs need the most help.  So the person coding
the library module is the logical person to write the doc.  The doc
writing task can't in general be handed off to some random programmer
or writer.  It should be written by the same person who wrote the code.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

2005-12-05 Thread Steve Holden

Paul Rubin wrote:
 [EMAIL PROTECTED] writes:
 
Sounds like a subject matter expert is needed here, not a garden variety
tech writer or Python programmer.  Documentation of esoteric stuff requires,
well, esoteric knowledge.
 
 
 Yes, that's what I mean; coding a library module for an esoteric
 function requires that same esoteric knowledge, and those are the
 modules for which the docs need the most help.  So the person coding
 the library module is the logical person to write the doc.  The doc
 writing task can't in general be handed off to some random programmer
 or writer.  It should be written by the same person who wrote the code.

Or, better still, by an accomplished writer who has access to the code's 
author. This was indeed my experience in writing the docs for previously 
undocumented modules. The author was happy to help me by answering 
questions, and this did make the docs better than they'd otherwise have 
been.
-- 
Steve Holden   +44 150 684 7255  +1 800 494 3119
Holden Web LLC www.holdenweb.com
PyCon TX 2006  www.python.org/pycon/

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

Re: Bitching about the documentation...

Or, better still, by an accomplished writer who has access to the code's
author. This was indeed my experience in writing the docs for
previously
undocumented modules. The author was happy to help me by answering
questions, and this did make the docs better than they'd otherwise have
been. 

Now you're talking. The writer forces the programmer to explain how the
code works, in plain English, until the writer understands it. Then the
writer creates simple sentences written in the active voice with vivid
particular examples to illustrate. Voila. 

rd

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

Re: Bitching about the documentation...

Steve Holden [EMAIL PROTECTED] writes:
 Or, better still, by an accomplished writer who has access to the
 code's author. This was indeed my experience in writing the docs for
 previously undocumented modules. The author was happy to help me by
 answering questions, and this did make the docs better than they'd
 otherwise have been.

Yes, this can work pretty well for some modules, especially when
there's in-person contact rather than just email.  The total amount of
work done between the two people may be more than would be needed if
the coder just wrote the docs and got it over with.  But any way that
gets it done is fine.
-- 
http://mail.python.org/mailman/listinfo/python-list

Usenet falsehoods (was Re: Bitching about the documentation...)

2005-12-05 Thread Aahz

In article [EMAIL PROTECTED],
Grant Edwards  [EMAIL PROTECTED] wrote:

Hmm, I though he explained it:

  1) Not using your real name.

  2) A yahoo, aol, or hotmail address.

In the ancient and hallowed (by net standards) history of Usenet, both
of these (particularly the first one) have been pretty good predictors
of crankness.  The correlation isn't as high as it used to be, now that
hiding behind silly nicknames has apparently become socially acceptable
in other venues (web forums and boards and whatnot).

To use a Panix in-joke, how old are you, anyway?

I've been on the Net for more than fifteen years, and while this canard
about real names gets trotted out from time to time, it's quite clear
that many many people have been active on the Net *and* taken seriously
using names that aren't what you'd call a real name.  (People named
piglet, tigger, and pooh, just for example, who were active long
before I showed up.  Not to mention piranha.)

ObSheesh: Sheesh
-- 
Aahz ([EMAIL PROTECTED])   * http://www.pythoncraft.com/

Don't listen to schmucks on USENET when making legal decisions.  Hire
yourself a competent schmuck.  --USENET schmuck (aka Robert Kern)
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...


Paul Rubin http://[EMAIL PROTECTED] wrote:
 Steve Holden [EMAIL PROTECTED] writes:
  Or, better still, by an accomplished writer who has access to the
  code's author. This was indeed my experience in writing the docs for
  previously undocumented modules. The author was happy to help me by
  answering questions, and this did make the docs better than they'd
  otherwise have been.

 Yes, this can work pretty well for some modules, especially when
 there's in-person contact rather than just email.  The total amount of
 work done between the two people may be more than would be needed if
 the coder just wrote the docs and got it over with.  But any way that
 gets it done is fine.

Redhat's Fedora project seems to have a fairly well developed
program for recruiting and encouraging writers.

I thought when I looked at their material 6-12 months ago, I
read that they formally facilitated contact between a project's
developers and writer(s) doing the documentation.  But I couldn't
find anything specific on that when I looked just now.

They might be a source of some useful ideas though (assuming
you don't already know all this.)
http://www.fedora.redhat.com/projects/docs/
http://fedoraproject.org/wiki/DocsProject/NewWriters

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

Re: Bitching about the documentation...

2005-12-05 Thread François Pinard

[Ben Finney]

 please study this form, carefully read the small print, fill it
 properly and send the yellow copy at this address.

 ... so that it can go with all the other requests I get at various
 times from various people.

If he wants pink forms with blue borders, let him grant himself with 
pink forms with blue borders.  His way of managing has not to be mine.
If he declares being unable to read information unless it is written on 
a pink form with blue borders, he has a serious communication problem, 
that should not receive encouragement from me.

 Astonished, you just cannot believe what you hear.  Life is so
 short, you think, why one would ought to stand with such guys?

 Perhaps because you have asked them to do something that benefits you,

Or perhaps not so specifically.  When I (attempt to) submit a Python 
problem (documentation or otherwise), I'm hoping some benefit to the 
Python community in the long run.  One of those humble drops which, 
accumulated, make oceans.  Most of times, in practice, I already solved 
my actual problem.  I'm merely trying to be a good citizen.  However, 
when people tell me I'm not a good citizen unless _I_ fill pink forms 
with blue borders, I think they lost part of their good judgement.
If they really want pink forms, they should serve themselves by filling 
pink forms, and leave me and the world alone with these forms.

 As the room is full of other interesting people, you happily move on
 towards them.

 If you just want to have conversations, talk to whomever you like.
 If you want someone specific to voluntarily do something, yes, you'll
 have to meet them halfway by helping them help you.

I do not want to force anyone to anything.  This is mostly volunteer 
work.  You know that.  The problem I'm reporting here is this pink form 
mania.   _I_ would volunteer something, that they'd ask for pink forms.

I've been in the area of free software maintainance for a very long 
while, collobarated with maybe a hundred of maintainers, and 
corresponded with surely many thousands of users.  No doubt it was a lot 
of work overall, but at least, communication was easy going (usually).
It's a relatively recent phenomenon that maintainers go berzerk, foaming 
at the mouth over forms, borders, colors, and various other mania!  :-)

-- 
François Pinard   http://pinard.progiciels-bpi.ca
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[EMAIL PROTECTED] writes:
 Redhat's Fedora project seems to have a fairly well developed
 program for recruiting and encouraging writers.

Frankly I haven't been that impressed with the Fedora docs I've seen.
The LDP docs have generally been better.  Maybe I'm looking at the
wrong Fedora docs.  Fedora Core 4 also broke or changed a bunch of
code that worked perfectly well in FC3, as a side issue.

For a language environment like Python, the example I'd look to for
quality docs is probably CLtL2:

   http://www.cliki.net/CLtL2

The CMU link seems to be down right now.
-- 
http://mail.python.org/mailman/listinfo/python-list

Re: Bitching about the documentation...

[EMAIL PROTECTED] wrote:
[EMAIL PROTECTED] wrote:
[EMAIL PROTECTED] wrote:
--snip--
If you prefer the latest documentation, bookmark this page:

http://www.python.org/dev/doc/devel/index.html

Thanks I will keep that in mind. But the obvious risk is that it
will refer to language features and changes not in the current
version.

That's updated every few months, more frequently as new releases approach.

Well, the docs are what they are, I can find what I need.

And so it is with me too. But it often takes me much longer than it
should to find what I need. And everytime I (or you) don't find it in
Python's docs, that is evidence of the lack of quality of Python's
docs.

Are you
telling us you learned C#, smalltalk, lisp, C, perl, whatever, from 1
website only, without looking at any books, without spending any money
on IDEs or any software? Cause that's what you're asking here.

For perl and C, yes, that's (close to) what I'm telling you. Perl I
learned
exclusively from the man pages, before WWW. I used it for 10 years
before I ever bought a printed book. C I learned exclusively from the

KR book. I tried to learn Python from the official docs but found
it
impossible. I bought Beasley's book (I think this may have predated
Martelli's book but I don't remember) which I thought quite good and
which I still turn to before the Python docs in most cases.

So either spend a little money, buy the Nutshell and Cookbook, (or,

If one is required to buy a book to use free software, it is not
really free, is it?

look at dozens of books, and many excellent ones:
http://www.amazon.com/exec/obidos/tg/browse/-/285856/ref=dp_brlad_entry/103-3311503-6360648

Books are no different than anything else. There are a few good ones,
a lot of average ones, and a few bad ones. (Actually, the distribution
is probably skewed to the bad side because it is easier to write a bad
book than a good one). Also most of these books seem to be tutorial
in nature. That's not what I want. I want a clear, lucid, *concise*,
compete, accurate, description of Python (i.e. what Python's docs
should be.) Given that Beazley (and I presume Martelli) did that, and
the reference manuals of other languages did that, I don't see why
Python can't do that (other than the fact that writing documentation
is not fun for most people, and hard to do well.)

or spend some time, look at the 2 complete intro books published on the

I did. I thought they both were poor.

web, there's also:

http://aspn.activestate.com/ASPN/Cookbook/Python
http://python.codezoo.com/
http://sourceforge.net/softwaremap/trove_list.php?form_cat=178xdiscrim=178

That's a very good list and I will save a copy, thanks. But what
does it have to do with Python's documentation?

So i don't think you ca really say the lang spec, the VM and the dev
environment in general are poorly documented.

Are you under the impression that an assortment of pages
out on the internet constitutes (or substitutes for) the official
documentation that comes with python?

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

Re: Bitching about the documentation...