Michael Ekstrand <[EMAIL PROTECTED]> writes:
> On Fri, 09 Sep 2005 18:16:36 -0400
> Mike Meyer <[EMAIL PROTECTED]> wrote:
>> You need a better browser. Mine - at least on Unix - have an option to
>> dump textareas into text files, invoke my favorite editor on them, and
>> then read the file back i
In article <[EMAIL PROTECTED]>,
Michael Ekstrand <[EMAIL PROTECTED]> wrote:
>On Fri, 09 Sep 2005 18:16:36 -0400
>Mike Meyer <[EMAIL PROTECTED]> wrote:
>>
>> You need a better browser. Mine - at least on Unix - have an option to
>> dump textareas into text files, invoke my favorite editor on them,
On Fri, 09 Sep 2005 18:16:36 -0400
Mike Meyer <[EMAIL PROTECTED]> wrote:
> You need a better browser. Mine - at least on Unix - have an option to
> dump textareas into text files, invoke my favorite editor on them, and
> then read the file back in when the editor exits. Assuming i'm not
> running t
Florian Diesch <[EMAIL PROTECTED]> writes:
> A.M. Kuchling <[EMAIL PROTECTED]> wrote:
> Another problem with Wikis is that you have to be online to use them and
> can't use your favourite editor to write.
You need a better browser. Mine - at least on Unix - have an option to
dump textareas into te
In article <[EMAIL PROTECTED]>,
Steve Holden <[EMAIL PROTECTED]> wrote:
>Aahz wrote:
>> In article <[EMAIL PROTECTED]>,
>> Steve Holden <[EMAIL PROTECTED]> wrote:
>.>
>>>Bear in mind that the PSF made its very first grants last year. The
>>>reason none of those grants was awarded to a documenta
Adriaan Renting wrote:
> In my Windows days I realy liked the Borland documentation, it was
> way better as the Visual Studio/MSDev docs. Borland C++Builder used
> to come with a complete rewrite of the Win32 API docs, next to the
> docs of it's own API.
Yes, but the two are completely separat
>>>Terry Hancock <[EMAIL PROTECTED]> 08/31/05 11:59 pm >>>
|> >I have NEVER seen a closed source application or programming
|> >language that came with that much documentation and support.
|>
|>I'm no fan of Microsoft, but in general, the Win32 API is far
|>better documented than is Python. (J
Aahz wrote:
> In article <[EMAIL PROTECTED]>,
> Steve Holden <[EMAIL PROTECTED]> wrote:
>
>>Bear in mind that the PSF made its very first grants last year. The
>>reason none of those grants was awarded to a documentation project was
>>that the (volunteer) Grants Committee and helpers didn't see
In article <[EMAIL PROTECTED]>,
Steve Holden <[EMAIL PROTECTED]> wrote:
>
>Bear in mind that the PSF made its very first grants last year. The
>reason none of those grants was awarded to a documentation project was
>that the (volunteer) Grants Committee and helpers didn't see any
>documentation
Steve Holden <[EMAIL PROTECTED]> writes:
> > legitimate. Python's core developers are in a leadership position for
> > Python whether they like it or not; and users and volunteers absorb
> > the attitudes of the leaders.
>
> So, what you are saying is because the developers (I explain in
> anothe
[EMAIL PROTECTED] writes:
> Also, "not that long ago" must mean different things for different people.
> I think we've required logins for three years or more.
I hope you're not right and that it hasn't really been that long.
Yikes ;-).
--
http://mail.python.org/mailman/listinfo/python-list
Tim> [Paul Rubin]
>> Until not that long ago, it was possible to submit sf bugs without
>> being logged into sf. Why did that change?
Tim> To reduce tracker spam, to reduce tracker vandalism, and to make it
Tim> possible to contact submitters when needed.
Also, "not that lon
A.M. Kuchling wrote:
> On Fri, 02 Sep 2005 06:19:16 GMT,
> Dennis Lee Bieber <[EMAIL PROTECTED]> wrote:
>
>> My attempts at simple came in closer to the life insurance than
>>Lincoln -- forget about Hemingway; the only way I could approach his
>>writing was to stick to: Hello World; Go
[Paul Rubin]
> Until not that long ago, it was possible to submit sf bugs without
> being logged into sf. Why did that change?
To reduce tracker spam, to reduce tracker vandalism, and to make it
possible to contact submitters when needed.
--
http://mail.python.org/mailman/listinfo/python-list
On Fri, 2 Sep 2005 01:28:22 -0500,
Terry Hancock <[EMAIL PROTECTED]> wrote:
> Hmm. Still sounds like "there ought to be a wiki". I've seen references
> to two different ones on this thread. One was then debunked as a "failed
> experiment". The other just gave me a DNS lookup failure (may
On Thu, 1 Sep 2005 23:08:18 -0400,
Fred L. Drake, Jr. <[EMAIL PROTECTED]> wrote:
> Ideally, emails to docs at python.org would result in issues being created
> somewhere, simply so they don't get lost. It probably doesn't make sense for
> those to land in SourceForge automatically, sinc
On Fri, 02 Sep 2005 06:19:16 GMT,
Dennis Lee Bieber <[EMAIL PROTECTED]> wrote:
> My attempts at simple came in closer to the life insurance than
> Lincoln -- forget about Hemingway; the only way I could approach his
> writing was to stick to: Hello World; Good day; See you later; Bye
Paul Rubin wrote:
> Michael Sparks <[EMAIL PROTECTED]> writes:
>> > I've submitted a number of doc bugs to sourceforge and the ones
>> > that are simple errors and omissions do get fixed.
>>
>> Cool.
>
> Better than nothing, but it's only one class of problem, and maybe the
> easiest kind to rep
Michael Sparks <[EMAIL PROTECTED]> writes:
> > I've submitted a number of doc bugs to sourceforge and the ones that
> > are simple errors and omissions do get fixed.
>
> Cool.
Better than nothing, but it's only one class of problem, and maybe the
easiest kind to report.
There's another type
On Thursday 01 September 2005 10:11 pm, Paul Rubin wrote:
> "Fred L. Drake, Jr." <[EMAIL PROTECTED]> writes:
> > Ideally, emails to docs at python.org would result in issues being
> > created somewhere, simply so they don't get lost. It probably
> > doesn't make sense for those to land in SourceFo
On Thursday 01 September 2005 04:03 am, Fredrik Lundh wrote:
> Steve Holden wrote:
> > I agree that maintaining documentation is a generic problem of the open
> > source world, but it's a sad fact of life that generally people are
> > better-motivated to complain about documentation (and almost eve
Fred L. Drake, Jr. wrote:
> On Thursday 01 September 2005 22:53, Steve Holden wrote:
> > So, probably the best outcome of this current dialogue would be a change
> > to the bottom-of-page comment so instead of saying
> >
> > """Release 2.4, documentation updated on 29 November 2004.
> > See Ab
Paul Rubin wrote:
[snip snippety snip snip, snip snip]
>
> Calling the Python docs "worthless" is false and unconstructive;
> saying that the docs have shortcomings in part because the Python
> project itself places too little priority on doc quality is perfectly
> legitimate. Python's core devel
"Fred L. Drake, Jr." <[EMAIL PROTECTED]> writes:
> Ideally, emails to docs at python.org would result in issues being
> created somewhere, simply so they don't get lost. It probably
> doesn't make sense for those to land in SourceForge automatically,
> since then everyone has to read every plea fo
On Thursday 01 September 2005 22:53, Steve Holden wrote:
> So, probably the best outcome of this current dialogue would be a change
> to the bottom-of-page comment so instead of saying
>
> """Release 2.4, documentation updated on 29 November 2004.
> See About this document... for information o
Fredrik Lundh wrote:
> Rocco Moretti wrote:
>
>
>>Something a simple as allowing doc bugs to be submitted from a webform
>>w/o login would reduce the barrier to contribute. - Increasing the size
>>of the "About" text wouldn't hurt either. (To be honest, I've never
>>noticed that text before, and
Rocco Moretti wrote:
> Steve Holden wrote:
>
>
>>Every page of the docs links to "About this document", which contains
>>the following: """If you are able to provide suggested text, either to
>>replace existing incorrect or unclear material, or additional text to
>>supplement what's already av
Asbjørn Sæbø <[EMAIL PROTECTED]> writes:
> "Xah Lee" <[EMAIL PROTECTED]> writes:
>> I'm very sorry to say, that the Python doc is one of the worst possible
>> in the industry. [...]
> I suppose you are going to volounteer to fix it, then. Right?
He once did, for one part of it. The problem he ran
"Terry Reedy" <[EMAIL PROTECTED]> writes:
> "Rocco Moretti" <[EMAIL PROTECTED]> wrote in message
> news:[EMAIL PROTECTED]
>> There is just one giant roadblock to that suggestion - Sourceforge
>> requires a login to post bugs/patches.
>
> After reading this and the rest of your post, and rememberin
Bryan Olson enlightened us with:
> > Why don't you help us by improving the documentation?
>
> Workin' on it.
That's all I needed to know ;-)
Sybren
--
The problem with the world is stupidity. Not saying there should be a
capital punishment for stupidity, but why don't we just take the
safety la
On Thu, 1 Sep 2005 17:09:27 +0200,
Fredrik Lundh <[EMAIL PROTECTED]> wrote:
> the useredit approach I'm using over at the librarybook site works
> pretty well. for example, if you go to
That looks pleasantly simple.
I don't consider the pydoc.amk.ca experiment to have been really succes
A.M. Kuchling wrote:
> On 1 Sep 2005 05:04:33 -0700,
> Paul Boddie <[EMAIL PROTECTED]> wrote:
>> Please note that I'm not labelling you as a troll.
>
> No, he's simply barking mad. I was amused by a rec.arts.sf.written
> discussion [1] where Lee complains that Jonathan Swift (1667-1745)'s
> writ
Hi Paul,
Paul Rubin wrote:
> Michael Sparks <[EMAIL PROTECTED]> writes:
[[[ some random stuff, /intended/ at supporting people who have contributed
docs, rather than saying people who offer constructive suggestions are
bad. Possibly badly written. ]]]
> I've submitted a number of doc bugs to
"Paul Rubin" <"http://phr.cx"@NOSPAM.invalid> wrote in message
news:[EMAIL PROTECTED]
> I think there is an attitude problem in the central Python development
> community, which is to expect external volunteers to do stuff with no
> cajoling and no guidance.
You are correct. No one has voluntee
"Rocco Moretti" <[EMAIL PROTECTED]> wrote in message
news:[EMAIL PROTECTED]
> There is just one giant roadblock to that suggestion - Sourceforge
> requires a login to post bugs/patches.
After reading this and the rest of your post, and remembering others like
it, I decided this maybe is a real
"Fredrik Lundh" <[EMAIL PROTECTED]> writes:
> another problem is that to be able to do really good work on the
> documentation, you need to know things well enough to "have the
> big picture". and once you have that, you'll find that the docs aren't
> really as bad as you once thought they were.
On 1 Sep 2005 03:51:55 -0700, "Xah Lee" <[EMAIL PROTECTED]> wrote:
>On Python's Documentation
Thinking about it, I can't imagine why I've waited so long to filter
this idiot.
--
Al Balmer
Balmer Consulting
[EMAIL PROTECTED]
--
http://mail.python.org/mailman/listinfo/python-list
> I'm very sorry to say, that the Python doc is one of the worst possible
> in the industry.
you are entitled to a full refund
--
http://mail.python.org/mailman/listinfo/python-list
A.M. Kuchling wrote:
> I was amused by a rec.arts.sf.written discussion [1] where Lee complains that
> Jonathan Swift (1667-1745)'s writing was unclear in style; apparently he's
> not aware
> that conventions and styles change over time.
Still, ill-founded assumptions about language could be much
On Thu, 1 Sep 2005, Asbjørn Sæbø wrote:
> I suppose you are going to volounteer to fix it, then. Right?
I wish he'd just volunteer to shut up--permanently.
--
Rich Teer, SCNA, SCSA, OpenSolaris CAB member
President,
Rite Online Inc.
Voice: +1 (250) 979-1638
URL: http://www.rite-group.com/ric
Rocco Moretti wrote:
> Something a simple as allowing doc bugs to be submitted from a webform
> w/o login would reduce the barrier to contribute. - Increasing the size
> of the "About" text wouldn't hurt either. (To be honest, I've never
> noticed that text before, and it never occurred to me look
Steve Holden wrote:
> Every page of the docs links to "About this document", which contains
> the following: """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
On Wed, 31 Aug 2005 19:57:00 GMT,
Bryan Olson <[EMAIL PROTECTED]> wrote:
> Since "help *is* pydoc.help, or at least...", the call could
> show the same thing as help(pydoc.help), or at least inform the
> user that more of the story is available from help(pydoc.help).
But, given that the h
On 1 Sep 2005 05:04:33 -0700,
Paul Boddie <[EMAIL PROTECTED]> wrote:
> Please note that I'm not labelling you as a troll.
No, he's simply barking mad. I was amused by a rec.arts.sf.written
discussion [1] where Lee complains that Jonathan Swift (1667-1745)'s writing
was unclear in style;
"Xah Lee" <[EMAIL PROTECTED]> writes:
> I'm very sorry to say, that the Python doc is one of the worst possible
> in the industry. [...]
I suppose you are going to volounteer to fix it, then. Right?
Asbjørn
--
Asbjørn Sæbø, post.doc.
Centre for Quantifiable Quality of Service in Communicatio
Xah Lee wrote:
> The "Language Reference" section (subtitled "for language
> lawyers") needs to be replaced by human-readible descriptions of
> Python's functions. For exapmle, in the style of official Java doc
> (http://java.sun.com/j2se/1.4.2/docs/api/index.html).
Nope. The Java documentation yo
Steve Holden wrote:
> I agree that maintaining documentation is a generic problem of the open
> source world, but it's a sad fact of life that generally people are
> better-motivated to complain about documentation (and almost everything
> else) than to help improve it.
another problem is that to
On Python's Documentation
Xah Lee, 20050831
I'm very sorry to say, that the Python doc is one of the worst possible
in the industry. I'm very sick of Perl and its intentional obfuscation
and juvenile drivel style of its docs. I always wanted to learn Python
as a replacement of Perl, and this year
By the way, i have sent my criticisms to the proper python doc
maintainer or mailing list several months ago.
-
i'm very sorry to say, that the Python doc is one of the worst possible
in the industry. I'm very sick of Perl and its intentional obfuscation
and juvenile drivel style of i
Fredrik Lundh wrote:
> Bryan Olson wrote:
>> import pydoc
>> help is pydoc.help
>> >
>> > False
>>
>>Say Fredrik, if you're going to proclaim "False"
>
> oh, I didn't proclaim anything. Python 2.4 did.
False. ;) That was all you.
> let's see what
> Python 2.2 has to say about
Michael Sparks <[EMAIL PROTECTED]> writes:
> > A plausible theory. I have some possibly-illustrative examples
> > of what I ran into within the last few weeks.
>
> Did you take what you learnt, and use that to create better
> documentation to be posted on python's SF project as a patch?
>
I've
Michael Sparks wrote:
> Bryan Olson wrote:
>>A plausible theory. I have some possibly-illustrative examples
>>of what I ran into within the last few weeks.
>
>
> Did you take what you learnt, and use that to create better
> documentation to be posted on python's SF project as a patch?
>
>
> (
"Robert Kern" <[EMAIL PROTECTED]> wrote in message
news:[EMAIL PROTECTED]
> Or perhaps more to the point, that http://pydoc.amk.ca/frame.html should
> be better-publicized.
This seems to be an experiment that has not been updated since 2.3.4.
tjr
--
http://mail.python.org/mailman/listinfo/p
> Bryan Olson wrote:
>> Whatever else one says about open-source documentation, keeping
>> it current is a major unsolved problem.
Python does pretty well. Doc updates, when needed, are an expected part of
patches. Every couple of months or so, F. Drake releases a new
'development version' of
Steve Holden wrote:
> Terry Hancock wrote:
>>Perhaps this just reduces to "there ought to be a wiki"?
>
> Well, perhaps the Wiki at http://wiki.python.org/moin/ should also be
> better-publicized, then?
Or perhaps more to the point, that http://pydoc.amk.ca/frame.html should
be better-publicize
Terry Hancock wrote:
> On Wednesday 31 August 2005 07:05 pm, Michael Sparks wrote:
>
>>When people complain /in here/ about the documentation not being perfect for
>>python I personally find it sad and ironic. It's sad because it says to the
>>person who spent their time (when they could be doing
On Wednesday 31 August 2005 07:05 pm, Michael Sparks wrote:
> When people complain /in here/ about the documentation not being perfect for
> python I personally find it sad and ironic. It's sad because it says to the
> person who spent their time (when they could be doing something else) that
> the
Bryan Olson wrote:
> A plausible theory. I have some possibly-illustrative examples
> of what I ran into within the last few weeks.
Did you take what you learnt, and use that to create better
documentation to be posted on python's SF project as a patch?
(Not aimed at you, just a preface, and
Bryan Olson wrote:
> import pydoc
> help is pydoc.help
> >
> > False
>
> Say Fredrik, if you're going to proclaim "False"
oh, I didn't proclaim anything. Python 2.4 did. let's see what
Python 2.2 has to say about this:
$ python2.2
Python 2.2.1 (#2, Jul 17 2002, 13:11:01)
[GCC 2.96
Sybren Stuvel wrote:
> I don't have any problems with the documentation. It just works for
> me. If you find any errors or omissions, fix them and send the
> document maintainer an email. Why don't you help us by improving the
> documentation?
Workin' on it.
--
--Bryan
--
http://mail.pytho
Fredrik Lundh wrote:
> Bryan Olson wrote:
>>[...]
>> > What additions to that string would you suggest?
>>
>>Since "help *is* pydoc.help, or at least...", the call could
>>show the same thing as help(pydoc.help)
>
>
import pydoc
help is pydoc.help
>
> False
Say Fredrik, if you'
Bryan Olson wrote:
> [...]
> > What additions to that string would you suggest?
>
> Since "help *is* pydoc.help, or at least...", the call could
> show the same thing as help(pydoc.help)
>>> import pydoc
>>> help is pydoc.help
False
> or at least inform the user that more of the story is availa
On Wednesday 31 August 2005 07:14 am, Bryan Olson wrote:
> Terry Hancock wrote:
> > Bryan Olson wrote:
> Then how does one distinguish stable, supported services, from
> incidental behavior that can change without notice?
Surprisingly often, "common sense" seems to be a workable answer
here. I'm
On Tuesday 30 August 2005 05:15 pm, Benji York wrote:
> Terry Hancock wrote:
> > OTOH, there are lots of poorly-documented third-party Python
> > modules (as in any language). Zope is a particularly nasty
> > example -- though I think I understand some of the reasons
> > behind that (rapidly chan
A.M. Kuchling wrote:
> Bryan Olson wrote:
>
>>I use dir() all the time; help() not so much. Typing help(help)
>>shows:
>>
>> Help on _Helper in module site:
>>
>> Type help() for interactive help, or help(object) for help
>> about object.
>>
>>That strikes me as not-particula
On Wed, 31 Aug 2005 12:14:35 GMT,
> I use dir() all the time; help() not so much. Typing help(help)
> shows:
>
> Help on _Helper in module site:
>
> Type help() for interactive help, or help(object) for help
> about object.
>
> That strikes me as not-particularly-helpful. Surely it
Terry Hancock wrote:
> Bryan Olson wrote:
>
>>I don't see any need to look beyond Python for a good example of
>>poor documentation. Are there serious Python programmers who
>>don't constantly struggle with errors and omissions in the doc?
>
> Uh, yes, actually.
>
> IMHO, the available Py
"Adriaan Renting" <[EMAIL PROTECTED]> writes:
> The good commercial docs are better because there it is understood
> how important this is.
Also, they are probably written by people who are trained technical
writers which has to help at least a bit... writing good documentation
is hard.
Whether
Bryan Olson enlightened us with:
> I don't see any need to look beyond Python for a good example of
> poor documentation. Are there serious Python programmers who don't
> constantly struggle with errors and omissions in the doc?
I don't have any problems with the documentation. It just works for
Terry Hancock wrote:
> OTOH, there are lots of poorly-documented third-party Python
> modules (as in any language). Zope is a particularly nasty
> example -- though I think I understand some of the reasons
> behind that (rapidly changing API, poor interaction with doc
> tools, etc).
Are you refe
On Tuesday 30 August 2005 02:32 am, Bryan Olson wrote:
> I don't see any need to look beyond Python for a good example of
> poor documentation. Are there serious Python programmers who
> don't constantly struggle with errors and omissions in the doc?
Uh, yes, actually.
IMHO, the available Python
Bryan Olson wrote:
> Adriaan Renting wrote:
> [...]
>
> > I do agree that a lot of OSS projects seem to lack somewhat in
> > the documentation department, compared to a lot of commercial
> > software. I would give the man page of gcc as an example, it's
> > just one 6600 line blurb.
>
> I don
Adriaan Renting wrote:
[...]
> I do agree that a lot of OSS projects seem to lack somewhat in
> the documentation department, compared to a lot of commercial
> software. I would give the man page of gcc as an example, it's
> just one 6600 line blurb.
I don't see any need to look beyond Python
"Adriaan Renting" <[EMAIL PROTECTED]> writes:
> Marked -1 Flamebait, but I'll respond anyway.
Yup.
> I do agree that a lot of OSS projects seem to lack somewhat in the
> documentation department, compared to a lot of commercial software.
You know what? My experience is just the opposite. Commerc
"Adriaan Renting" <[EMAIL PROTECTED]> writes:
> He seems to think the GNU man pages are nice, but I find them very
> awkward as they have no hierarchical organization, and most miss examples.
The GNU man pages are an afterthought to meet expectations of Un*x
users who were used to man pages and th
Marked -1 Flamebait, but I'll respond anyway.
I've read the documents he refers to, and although I agree that the Python docs
aren't perfect, I do not agree with him on which points. I for example do think
it's important to incude info on which versions of the language support a
feature.
He see
On Sat, 27 Aug 2005, Xah Lee wrote:
His usual crap.
___
/| /| | |
||__|| | Please do |
/ O O\__ NOT |
/
previously i've made serious criticisms on Python's documentations
problems.
(see http://xahlee.org/perl-python/re-write_notes.html )
I have indicated that a exemplary documentation is Wolfram Research
Incorporated's Mathematica language. (available online at
http://documents.wolfram.com/mathemati
78 matches
Mail list logo
