Discussion:
Bitching about the documentation...
(too old to reply)
BartlebyScrivener
2005-12-05 19:01:43 UTC
Permalink
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
Tony Meyer
2005-12-05 00:39:55 UTC
Permalink
>> Among the treasures available in The Wiki is the current
>> copy of "the Sorting min-howto":
>> http://www.amk.ca/python/howto/sorting/sorting.html
>
> Why is this a "treasure" when it is way out of date?

Note that the updated version of this is at: http://wiki.python.org/
moin/HowTo/Sorting

=Tony.Meyer
skip
2005-12-05 01:05:00 UTC
Permalink
>>> Among the treasures available in The Wiki is the current
>>> copy of "the Sorting min-howto":
>>> http://www.amk.ca/python/howto/sorting/sorting.html
>>
>> Why is this a "treasure" when it is way out of date?

Tony> Note that the updated version of this is at:
Tony> http://wiki.python.org/moin/HowTo/Sorting

And has been updated quite a bit in the last week by Andrew.

Skip
Aahz
2005-12-05 18:49:45 UTC
Permalink
In article <mailman.1635.1133803625.18701.python-list at python.org>,
<skip at pobox.com> wrote:
>
> Tim Peters? Read it no matter what the subject says.

A-men!
--
Aahz (aahz at pythoncraft.com) <*> 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)
rurpy
2005-12-05 22:37:51 UTC
Permalink
<skip at pobox.com> wrote in message
news:mailman.1628.1133798275.18701.python-list at python.org...
--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.
Fredrik Lundh
2005-12-05 22:59:40 UTC
Permalink
rurpy at yahoo.com 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>
Grant Edwards
2005-12-05 23:52:01 UTC
Permalink
On 2005-12-05, rurpy at yahoo.com <rurpy at yahoo.com> 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
Fredrik Lundh
2005-12-06 00:28:13 UTC
Permalink
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>
rurpy
2005-12-05 23:18:59 UTC
Permalink
Fredrik Lundh wrote:
> rurpy at yahoo.com 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 ;-)
skip
2005-12-06 11:46:18 UTC
Permalink
>> 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
skip at pobox.com
Fredrik Lundh
2005-12-07 13:30:48 UTC
Permalink
skip at pobox.com 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>
Steven D'Aprano
2005-12-07 17:50:16 UTC
Permalink
On Wed, 07 Dec 2005 07:50:14 -0800, Alex Martelli wrote:

> Steven D'Aprano <steve at REMOVETHIScyber.com.au> 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.
skip
2005-12-07 18:48:03 UTC
Permalink
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
Bengt Richter
2005-12-05 20:56:50 UTC
Permalink
On 5 Dec 2005 10:53:36 -0800, aahz at pythoncraft.com (Aahz) wrote:

>In article <1133806205.373629.178540 at g44g2000cwa.googlegroups.com>,
>BartlebyScrivener <rpdooling at gmail.com> 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
A.M. Kuchling
2005-12-06 14:51:25 UTC
Permalink
On Mon, 05 Dec 2005 20:56:50 GMT,
Bengt Richter <bokr at oz.net> 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
Dan Sommers
2005-12-08 01:44:44 UTC
Permalink
On Thu, 08 Dec 2005 12:19:13 +1100,
Steven D'Aprano <steve at REMOVETHIScyber.com.au> 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/>
Tony Meyer
2005-12-05 07:24:31 UTC
Permalink
> 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?

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

> Documentation is certainly one of them.

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

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

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.

=Tony.Meyer
Jon Perez
2005-12-07 13:41:16 UTC
Permalink
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.
Steve Holden
2005-12-06 03:56:32 UTC
Permalink
Paul Rubin wrote:
> skip at pobox.com 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/
skip
2005-12-06 03:26:08 UTC
Permalink
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 webmaster at python.org.

Skip
Jon Perez
2005-12-07 16:49:49 UTC
Permalink
rurpy at yahoo.com 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).
unknown
2005-12-06 05:19:21 UTC
Permalink
"BartlebyScrivener" <rpdooling at gmail.com> writes:

> >>The solution is clear: the distro maintainers should require that all
> code contributions must come with good docs.
> 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.

I've generally found good coders are also good writers, despite the
stereotype of the uncommunicative geek. Some coders don't like
documenting because it's less exciting than writing code, but that
doesn't mean they're incapable of it. After a while you learn to just
slog it out.

Docs written by non-native English speakers generally need to be
cleaned up before publication, but that's no big deal.

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

I just don't know to what extent a program like Python can really
benefit from docs written by non-experts in the thing being
documented. Of course there are other types of programs, like some
desktop applications, which can be documented by non-experts.

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

I don't know about this.

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

PHP has a system sort of like that, where each library function has
its own doc page and anyone can submit comments and examples, sort
of like a blog. E.g.:

http://us2.php.net/manual/en/function.metaphone.php

There's been some discussion of doing the same thing for Python, but
it hasn't been happening.

Generally, it seems to me, the parts of the docs that can be improved
much by easy additions like an example here and there, are already
usable with a little extra effort. The docs that need improvement the
most (because they're almost unusable as-is) need extensive additions
and rewrites that really have to to be done by experts.

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

Maybe you'd enjoy going to a user group meeting and trying to find
people to collaborate with. Doing that kind of thing in person is
much more fun than doing it over the net.
Christopher Subich
2005-12-07 18:19:03 UTC
Permalink
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. :)
Peter Hansen
2005-12-05 04:54:46 UTC
Permalink
rurpy at yahoo.com wrote:
> skip at pobox.com 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.

No, he's talking about the *wiki* search box, not the one in the extreme
upper right which is for the whole site. Scan down just a tad... it's
got a yellow background here (in Firefox).

Admittedly not at all obvious, especially sitting next to the "Login"
link and looking like maybe a text field for a user name or something,
though it does clearly have the word "Search" in it until you click
there...

-Peter
Steve Holden
2005-12-08 09:45:10 UTC
Permalink
Michael Spencer wrote:
[...]
> 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
>
All this remind me about the Member of Parliament who was required to
apologise for calling one of his opposite numbers a liar. He did so by
reading out the statement

"I called the Honorable member a liar it is true and I am sorry for it",
adding that the Honorable member could insert the punctuation wherever
he so chose.

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/
gene tani
2005-12-06 02:01:47 UTC
Permalink
rurpy at yahoo.com wrote:
> skip at pobox.com 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=178&xdiscrim=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.
gene tani
2005-12-06 13:43:10 UTC
Permalink
skip at pobox.com 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 K&R 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 K&R buying a
book? In the meantime, use the resources, Luke (i think i've been on
usenet too long... signing out)
Ben Finney
2005-12-06 05:45:45 UTC
Permalink
rurpy at yahoo.com wrote:
> If one is required to buy a book to use free software, it is not
> really free, is it?

If one is required to buy a computer to use free software, is it free?

You should well know that cost and freedom are orthogonal.

--
\ "I got fired from my job the other day. They said my |
`\ personality was weird. ... That's okay, I have four more." -- |
_o__) Bug-Eyed Earl, _Red Meat_ |
Ben Finney
Steven D'Aprano
2005-12-07 11:08:53 UTC
Permalink
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.
Simon Brunning
2005-12-07 12:21:58 UTC
Permalink
On 12/7/05, Steven D'Aprano <steve at removethiscyber.com.au> 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
skip
2005-12-06 11:54:06 UTC
Permalink
>> 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 K&R 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
rurpy
2005-12-06 05:05:46 UTC
Permalink
<gene.tani at gmail.com> wrote:
> rurpy at yahoo.com wrote:
> > skip at pobox.com 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

K&R 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://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=178&xdiscrim=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

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?
Tony Meyer
2005-12-05 02:24:24 UTC
Permalink
>>>> Among the treasures available in The Wiki is the current
>>>> copy of "the Sorting min-howto":
>>>> http://www.amk.ca/python/howto/sorting/sorting.html
>>>
>>> Why is this a "treasure" when it is way out of date?
>>
>> Note that the updated version of this is at: http://wiki.python.org/
>> moin/HowTo/Sorting
>
> http://wiki.python.org/...

Read the message more carefully. Mail wrapped the URL - if you put
it back together, it'll be there. To make it easy, try:

<http://wiki.python.org/moin/HowTo/Sorting>

<http://tinyurl.com/bkwf7>

> [...]
> Maybe I should Goole python.org What was the google syntax to
> limit the search to one site? I forgot.

It's "site:", but even if you just left that out and used
'wiki.python.org sorting "how to"', the first link is the one you're
after. Laziness is no excuse.

> Wikis suck. Update the damn docs.

The documentation *has* been updated. If you read the Python 2.5
documentation (build it, or wait for Python 2.5 to be released),
you'll see that it points to the Wiki.

=Tony.Meyer
BartlebyScrivener
2005-12-08 20:16:15 UTC
Permalink
The actress Margaret Anglin left this note in the dressing froom of
another actress:

'Margaret Anglin says Mrs. Fiske is the best actress in America.'

Mrs. Fiske added two commas and returned the note: 'Margaret Anglin,
says Mrs. Fiske, is the best actress in America.'

Or this, from a George Will column:

Huge doctrinal consequences flow from the placing of a comma in what
Jesus, when on the cross, said to the thief (Luke 23:43): 'Verily, I
say unto thee, This day thou shalt be with me in Paradise' or 'Verily,
I say unto thee this day, Thou shalt be with me in Paradise.' The
former leaves little room for purgatory.
Aahz
2005-12-06 04:45:00 UTC
Permalink
In article <11p9kl1cm57dr7b at corp.supernews.com>,
Grant Edwards <grante at visi.com> 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 (aahz at pythoncraft.com) <*> 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)
Grant Edwards
2005-12-06 06:08:36 UTC
Permalink
On 2005-12-06, Aahz <aahz at pythoncraft.com> wrote:
> In article <11p9kl1cm57dr7b at corp.supernews.com>,
> Grant Edwards <grante at visi.com> 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?

Hmm, let's see....

"Wasting Time on Usenet Since 1989"

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

--
Grant Edwards grante Yow! Uh-oh!! I'm having
at TOO MUCH FUN!!
visi.com
Aahz
2005-12-06 18:14:45 UTC
Permalink
In article <11paan4og361529 at corp.supernews.com>,
Grant Edwards <grante at visi.com> wrote:
>On 2005-12-06, Aahz <aahz at pythoncraft.com> wrote:
>> In article <11p9kl1cm57dr7b at corp.supernews.com>,
>> Grant Edwards <grante at visi.com> 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 (aahz at pythoncraft.com) <*> 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)
Erik Max Francis
2005-12-06 05:57:19 UTC
Permalink
Aahz wrote:

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

The fact that it obviously isn't always true without exception doesn't
mean it's never true. Or did that not occur to you?

--
Erik Max Francis && max at alcyone.com && http://www.alcyone.com/max/
San Jose, CA, USA && 37 20 N 121 53 W && AIM erikmaxfrancis
Always forgive your enemies -- nothing annoys them so much.
-- Oscar Wilde
Dave Hansen
2005-12-08 15:49:40 UTC
Permalink
On Wed, 07 Dec 2005 12:33:07 -0600 in comp.lang.python, Rocco Moretti
<roccomoretti at hotpop.com> wrote:

[...]

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

I've seen this before as

bill had had had but will had had had had had had or had had been
correct had had had

Regards,
-=Dave

--
Change is inevitable, progress is not.
bonono
2005-12-05 16:26:09 UTC
Permalink
skip at pobox.com 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.
skip
2005-12-05 17:26:55 UTC
Permalink
>> 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
unknown
2005-12-06 05:05:00 UTC
Permalink
rurpy at yahoo.com 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.
rurpy
2005-12-05 05:50:39 UTC
Permalink
Peter Hansen wrote:
> rurpy at yahoo.com wrote:
> > skip at pobox.com wrote:
snip
> > 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.
>
> No, he's talking about the *wiki* search box, not the one in the extreme
> upper right which is for the whole site. Scan down just a tad... it's
> got a yellow background here (in Firefox).
>
> Admittedly not at all obvious, especially sitting next to the "Login"
> link and looking like maybe a text field for a user name or something,
> though it does clearly have the word "Search" in it until you click
> there...

It certainly did fool me. :-(
rurpy
2005-12-05 01:16:00 UTC
Permalink
Tony Meyer wrote:
> >> Among the treasures available in The Wiki is the current
> >> copy of "the Sorting min-howto":
> >> http://www.amk.ca/python/howto/sorting/sorting.html
> >
> > Why is this a "treasure" when it is way out of date?
>
> Note that the updated version of this is at: http://wiki.python.org/
> moin/HowTo/Sorting
>
> =Tony.Meyer

http://wiki.python.org/...
Hmmm, lets see, how about Libraries?
Nope, don't see anything that looks like it might be about sort
there...
How about Documentation?
Nope
Code?
Hmm, "sort lists of dicts" doesn't sound like it...
I see there a search box, let's try that for "sort"
WTF?, these all look like old maillist archives...
Maybe I should Goole python.org What was the google syntax to
limit the search to one site? I forgot.
Aww screw it.

Wikis suck. Update the damn docs.
rurpy
2005-12-05 22:10:00 UTC
Permalink
"Tony Meyer" <t-meyer at ihug.co.nz> wrote:
> >> It's "site:", but even if you just left that out and used
> >> 'wiki.python.org sorting "how to"', the first link is the one you're
> >> after. Laziness is no excuse.
> >
> > You miss my point. Having outdated documentaion distributed
> > with Python is the problem. Have some newer stuff out on some
> > wiki is nice but does not fix the problem. I know people don't like
> > writing and updating docs. But that doesn't turn bad documentation
> > in good.
> >
> >>> Wikis suck. Update the damn docs.
> >>
> >> The documentation *has* been updated. If you read the Python 2.5
> >> documentation (build it, or wait for Python 2.5 to be released),
> >> you'll see that it points to the Wiki.
>
> You're complaining about something that has been fixed. The
> documentation was out of date, and that has been corrected. If you
> really must complain about something (in the interests of a foolish
> 'balance'), then pick something that hasn't been fixed.

Well, I was running Python-2.4.1 so I upgraded to 2.4.2 and guess
what? The docs still reference the old Howto. Perhaps you meant
to say "will be fixed in 2.5" rather than "has been fixed"?

> Note that having the core information in the documentation and
> additional information like "how-to"s in a wiki means that keeping it
> up-to-date isn't tied to a release.
A.M. Kuchling
2005-12-06 14:30:55 UTC
Permalink
On 5 Dec 2005 14:10:00 -0800,
rurpy at yahoo.com <rurpy at yahoo.com> wrote:
> Well, I was running Python-2.4.1 so I upgraded to 2.4.2 and guess
> what? The docs still reference the old Howto. Perhaps you meant
> to say "will be fixed in 2.5" rather than "has been fixed"?

The docs reference the sorting howto? Can someone please tell me
where so that I can check that the URL is correct? (grep doesn't turn
it up, so I suspect you're talking about something other than the
Python documentation.)

--amk
Tony Meyer
2005-12-05 23:46:13 UTC
Permalink
> Well, I was running Python-2.4.1 so I upgraded to 2.4.2 and guess
> what? The docs still reference the old Howto. Perhaps you meant
> to say "will be fixed in 2.5" rather than "has been fixed"?

No, I meant has been fixed. A fixed version hasn't been released,
but that doesn't make it any less fixed.

=Tony.Meyer
Steve Holden
2005-12-06 02:42:57 UTC
Permalink
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/
Rocco Moretti
2005-12-07 18:33:07 UTC
Permalink
>>>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
Michael Spencer
2005-12-07 21:07:15 UTC
Permalink
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
Rocco Moretti
2005-12-08 15:08:20 UTC
Permalink
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?

Quote marks are acceptable, but no more than two words are inside each set.


B
A
D
G
E
R

.
.
.

E
R


S
P
O
I
L
E
R

W
A
R
N
I
N
G

The "accepted" way to do it is:

Fred, where Guido had had "had", had had "had had." "Had had" had had a
better effect on the reader.

meaning approximately

In the place where Guido previously put the word "had", Fred had
previously put the phrase "had had." Fred's choice of phrasing was more
appreciated by the reder.
Fredrik Lundh
2005-12-07 18:58:57 UTC
Permalink
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>
BartlebyScrivener
2005-12-05 18:10:05 UTC
Permalink
>> 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
skip
2005-12-05 23:26:56 UTC
Permalink
>>>>> "bs" == BartlebyScrivener <rpdooling at gmail.com> 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
unknown
2005-12-07 03:20:43 UTC
Permalink
Fran?ois Pinard <pinard at iro.umontreal.ca> 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.
Fredrik Lundh
2005-12-07 18:22:43 UTC
Permalink
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>
Sion Arrowsmith
2005-12-08 17:46:20 UTC
Permalink
Steven D'Aprano <steve at REMOVETHIScyber.com.au> wrote:
>>> "Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo."
>
>S
>P
>O
>I
>L
>E
>R
>
>S
>P
>A
>C
>E
>


(Good grief, I've not done that in *years*.)

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

I *think* that's similar to the one I know about the cannibalistic
behaviour of some oysters, which split open other oysters (to eat
them). It starts:

"Oysters oysters split split."

Oysters which oysters split become split.

But there's nothing to stop a third set of oysters predating on the
ones doing the splitting:

"Oysters oysters oysters split split split."

And so on. My brain hurts too much to work out if you can do the
same to the buffaloes.

And here endeth today's lesson in recursion.

--
\S -- siona at chiark.greenend.org.uk -- http://www.chaos.org.uk/~sion/
___ | "Frankly I have no feelings towards penguins one way or the other"
\X/ | -- Arthur C. Clarke
her nu become? se bera eadward ofdun hl?ddre heafdes b?ce bump bump bump
François Pinard
2005-12-07 02:33:23 UTC
Permalink
[A.M. Kuchling]
>On Tue, 6 Dec 2005 00:05:38 -0500,
> Fran?ois Pinard <pinard at iro.umontreal.ca> 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
skip
2005-12-07 11:29:02 UTC
Permalink
>> 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
webmaster at python.org.

Skip
Steve Holden
2005-12-07 08:22:12 UTC
Permalink
Fran?ois Pinard wrote:
> [A.M. Kuchling]
>
>>On Tue, 6 Dec 2005 00:05:38 -0500,
>> Fran?ois Pinard <pinard at iro.umontreal.ca> 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, you talk of "the maintainer" as though each piece of code is
owned by a single individual. In Python's case this is far from the truth.

So, what you say *seems* to equate to "If there's a problem with Python
that I think should be fixed, I should be able to mail the person I
suspect is most likely to maintain that code, and they should be obliged
to log the bug or enhancement request in the tracking system".

There's also a philosophical question here about who is helping who. One
might choose to believe that the contributor is assisting the developer,
by pointing out a defect in the developer's code. One might
alternatively regard the contributor as a supplicant, who needs the
assistance of the developer to get a problem fixed. Finally one might
regard the contributor (who benefits from having Python available) and
the developer (who gets the kudos of having developed something "cool")
to be members of a community, prepared to collaborate to achieve
something that benefits them both.

In the real world people's opinions will have all kinds of other shades
as well, of course, but as far as *I'm* concerned, if the developers say
"please contribute bug reports through Sourceforge" then I am happy to
do so to make sure they don't fall between the cracks and get lost. YMMV.

Obviously the developers are in charge here, but I really don't see how
putting more load on them by requiring them to collectively be the only
sources of bug input to the tracking system will help get more work out
of them.

If you wanted to build a better tracking system than the one on
SourceForge I could certainly support that, but historically there
hasn't been much volunteer effort available to switch to something like
Roundup which might be preferred.

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/
A.M. Kuchling
2005-12-06 15:25:28 UTC
Permalink
On Tue, 6 Dec 2005 00:05:38 -0500,
Fran?ois Pinard <pinard at iro.umontreal.ca> 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 mso at oz.net (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
Neil Schemenauer
2005-12-08 18:03:24 UTC
Permalink
Fran?ois Pinard <pinard at iro.umontreal.ca> wrote:
>[AMK]
>> 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...
>
>> 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.

Either I don't understand what you are saying or you are being a
hypocrite. Andrew is saying that he doesn't have time to detail
with all the messages that get sent to him personally. What do you
propose he should do? I think people expect more that a message
saying "Thanks for you contribution. PS: Since I don't have time to
do anything with it, your message will now be discarded.".

Neil
Grant Edwards
2005-12-07 15:29:07 UTC
Permalink
On 2005-12-07, Steven D'Aprano <steve at REMOVETHIScyber.com.au> 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
Fredrik Lundh
2005-12-07 18:20:28 UTC
Permalink
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>
Steven D'Aprano
2005-12-07 18:03:47 UTC
Permalink
On Wed, 07 Dec 2005 15:29:07 +0000, Grant Edwards wrote:

> On 2005-12-07, Steven D'Aprano <steve at REMOVETHIScyber.com.au> 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.
unknown
2005-12-06 03:39:35 UTC
Permalink
skip at pobox.com 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.
BartlebyScrivener
2005-12-06 04:14:24 UTC
Permalink
>>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
unknown
2005-12-06 04:40:28 UTC
Permalink
Steve Holden <steve at holdenweb.com> 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.
rurpy
2005-12-06 04:58:45 UTC
Permalink
"Paul Rubin" <http://phr.cx at NOSPAM.invalid> wrote:
> Steve Holden <steve at holdenweb.com> 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
Steven D'Aprano
2005-12-07 10:27:03 UTC
Permalink
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.
Mike Meyer
2005-12-07 22:15:03 UTC
Permalink
"Fredrik Lundh" <fredrik at pythonware.com> 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 <mwm at mired.org> http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
Steven D'Aprano
2005-12-08 01:19:13 UTC
Permalink
On Wed, 07 Dec 2005 17:15:03 -0500, Mike Meyer wrote:

> "Fredrik Lundh" <fredrik at pythonware.com> 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.
Alex Martelli
2005-12-07 15:50:14 UTC
Permalink
Steven D'Aprano <steve at REMOVETHIScyber.com.au> 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
Christopher Subich
2005-12-07 14:54:01 UTC
Permalink
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. :)
Fredrik Lundh
2005-12-07 10:45:04 UTC
Permalink
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>
Steven D'Aprano
2005-12-07 18:10:49 UTC
Permalink
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.
Christopher Subich
2005-12-07 18:20:11 UTC
Permalink
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.
Ben Finney
2005-12-06 03:36:47 UTC
Permalink
Fran?ois Pinard <pinard at iro.umontreal.ca> 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
François Pinard
2005-12-06 05:05:38 UTC
Permalink
[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
skip
2005-12-06 03:30:35 UTC
Permalink
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
BartlebyScrivener
2005-12-06 03:36:58 UTC
Permalink
>>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
Aahz
2005-12-07 19:29:57 UTC
Permalink
In article <dn79t4$fk5$1 at news.doit.wisc.edu>,
Rocco Moretti <roccomoretti at hotpop.com> 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 (aahz at pythoncraft.com) <*> 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)
François Pinard
2005-12-06 02:47:23 UTC
Permalink
[skip at pobox.com]

> 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
unknown
2005-12-06 03:16:12 UTC
Permalink
Fran?ois Pinard <pinard at iro.umontreal.ca> 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.
BartlebyScrivener
2005-12-05 23:44:20 UTC
Permalink
>>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
rurpy
2005-12-05 04:56:35 UTC
Permalink
Tony Meyer wrote:
> >>>> Among the treasures available in The Wiki is the current
> >>>> copy of "the Sorting min-howto":
> >>>> http://www.amk.ca/python/howto/sorting/sorting.html
> >>>
> >>> Why is this a "treasure" when it is way out of date?
> >>
> >> Note that the updated version of this is at: http://wiki.python.org/
> >> moin/HowTo/Sorting
> >
> > http://wiki.python.org/...
>
> Read the message more carefully. Mail wrapped the URL - if you put
> it back together, it'll be there. To make it easy, try:

Mea culpa, I did miss that.

> <http://wiki.python.org/moin/HowTo/Sorting>
>
> <http://tinyurl.com/bkwf7>
>
> > [...]
> > Maybe I should Goole python.org What was the google syntax to
> > limit the search to one site? I forgot.
>
> It's "site:", but even if you just left that out and used
> 'wiki.python.org sorting "how to"', the first link is the one you're
> after. Laziness is no excuse.

You miss my point. Having outdated documentaion distributed
with Python is the problem. Have some newer stuff out on some
wiki is nice but does not fix the problem. I know people don't like
writing and updating docs. But that doesn't turn bad documentation
in good.

> > Wikis suck. Update the damn docs.
>
> The documentation *has* been updated. If you read the Python 2.5
> documentation (build it, or wait for Python 2.5 to be released),
> you'll see that it points to the Wiki.

Hmm, not sure what I think about that (pointing to wiki).

> =Tony.Meyer
Tony Meyer
2005-12-05 07:09:49 UTC
Permalink
>> It's "site:", but even if you just left that out and used
>> 'wiki.python.org sorting "how to"', the first link is the one you're
>> after. Laziness is no excuse.
>
> You miss my point. Having outdated documentaion distributed
> with Python is the problem. Have some newer stuff out on some
> wiki is nice but does not fix the problem. I know people don't like
> writing and updating docs. But that doesn't turn bad documentation
> in good.
>
>>> Wikis suck. Update the damn docs.
>>
>> The documentation *has* been updated. If you read the Python 2.5
>> documentation (build it, or wait for Python 2.5 to be released),
>> you'll see that it points to the Wiki.

You're complaining about something that has been fixed. The
documentation was out of date, and that has been corrected. If you
really must complain about something (in the interests of a foolish
'balance'), then pick something that hasn't been fixed.

Note that having the core information in the documentation and
additional information like "how-to"s in a wiki means that keeping it
up-to-date isn't tied to a release.

=Tony.Meyer
rurpy
2005-12-05 22:17:30 UTC
Permalink
"Tony Meyer" <t-meyer at ihug.co.nz> 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.
rurpy
2005-12-05 04:44:21 UTC
Permalink
skip at pobox.com 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.
skip
2005-12-05 15:57:43 UTC
Permalink
>> 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
skip
2005-12-05 03:56:41 UTC
Permalink
>> Note that the updated version of this is at: http://wiki.python.org/
>> moin/HowTo/Sorting

rurpy> http://wiki.python.org/...
rurpy> Hmmm, lets see, how about Libraries?
rurpy> Nope, don't see anything that looks like it might be about sort
rurpy> there...
rurpy> How about Documentation?
rurpy> Nope
rurpy> Code?
rurpy> Hmm, "sort lists of dicts" doesn't sound like it...
rurpy> I see there a search box, let's try that for "sort"
rurpy> WTF?, these all look like old maillist archives...
rurpy> Maybe I should Goole python.org What was the google syntax to
rurpy> limit the search to one site? I forgot.
rurpy> Aww screw it.

rurpy> Wikis suck. Update the damn docs.

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

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.

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.

If you prefer the latest documentation, bookmark this page:

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

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

Skip
rurpy
2005-12-04 23:53:25 UTC
Permalink
"Cameron Laird" <python-url at phaseit.net> wrote:
snip
> Among the treasures available in The Wiki is the current
> copy of "the Sorting min-howto":
> http://www.amk.ca/python/howto/sorting/sorting.html
snip

Why is this a "treasure" when it is way out of date?

1. There is no mention of the key or reverse arguments.
2. Worse, it describes as normal practice, methods that the key
and reverse arguments makes obsolete.
3. There's no mention of sorted() or of the differences between sort()
and sorted().
Aahz
2005-12-05 18:53:36 UTC
Permalink
In article <1133806205.373629.178540 at g44g2000cwa.googlegroups.com>,
BartlebyScrivener <rpdooling at gmail.com> 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 (aahz at pythoncraft.com) <*> 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)
John J. Lee
2005-12-05 21:38:41 UTC
Permalink
"BartlebyScrivener" <rpdooling at gmail.com> 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
BartlebyScrivener
2005-12-05 19:39:04 UTC
Permalink
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
nick
2005-12-05 21:52:42 UTC
Permalink
"BartlebyScrivener" <rpdooling at gmail.com> 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: fdrake at acm.org

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)
Scott David Daniels
2005-12-05 19:18:18 UTC
Permalink
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
scott.daniels at acm.org
Continue reading on narkive:
Loading...