On 11/02/2010 02:42 PM, Steven D'Aprano wrote:
> However, there is a Python wiki. It doesn't get anywhere near as much
> love as it deserves, and (I think) the consensus was that the official
> Python docs should stay official, but link to the wiki for user-
> contributed content. This hasn't ha
In message , Cameron
Simpson wrote:
> But its weakness is stuff like this:
>
> http://epydoc.sourceforge.net/stdlib/Canvas.Polygon-class.html
>
> Automatic docness, no useful information.
But it Conforms to Documentation-Production Metrics as decreed by the
Corporate Task Force on Policy. S
On Thu, 04 Nov 2010 08:03:37 +1100, Cameron Simpson wrote:
> On 02Nov2010 04:23, jk wrote: | This
> (http://epydoc.sourceforge.net/stdlib/) is what I'm talking | about.
> |
> | Why aren't the official docs like this, and why has it taken me 2 days
> | of searching? All this needs is a search engi
On 02Nov2010 04:23, jk wrote:
| This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
| about.
|
| Why aren't the official docs like this, and why has it taken me 2 days
| of searching? All this needs is a search engine behind it and it'd be
| perfect.
It looks a lot like javadoc. But
On 02Nov2010 03:42, jk wrote:
| I've been coding in PHP and Java for years, and their documentation is
| concise, well structured and easy to scan.
While I agree about Java, at least the core Java docs, and javadoc
output in general (_great_ cross referencing!) I have mixed feelings
about the PHP
Steven D'Aprano writes:
> On Tue, 02 Nov 2010 03:42:22 -0700, jk wrote:
>> The former is difficult to find (try searching for 'open' in the search
>> box and see what you get).
>
> A fair point -- the built-in open comes up as hit #30, whereas searching
> for open in the PHP page brings up fopen a
On Nov 2, 11:06 pm, Lawrence D'Oliveiro wrote:
> In message
> , jk
> wrote:
>
> > This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
> > about.
>
> Framesets? Is that really your idea of well-laid-out documentation? Using a
> feature which has been derided (and dropped in HTML5) beca
In message , Dennis Lee
Bieber wrote:
> Whereas I have a whole shelf of Java documentation and it still
> takes me an hour to write "Hello World"... Java's one class per file
> results in a plethora of bloody names one has to remember just to find
> out where to start looking for a standard libra
AD i agree with you! The official python tutorial and the official
docs are pretty much a twisted mass of confusion to the initiated
programmer. Even today when i try yo search the docs i find the result
quite frankly useless. And the search reminds me of the old XP "puppy
dog" search. The doc AR
My 2c:
I use the ActiveState distro, and it's winhelp doco. It's generally ok
and some things, like Dive Into Python, I've found excellent.
But I do quite regularly find myself cursing at the vagueness of the
index, and some of the content seems to require that you know it before
you read i
In message <2010110223050345181-nizum...@mcnuggetscom>, Nizumzen wrote:
> On 2010-11-02 10:42:22 +, jk said:
>
>> I've been coding in PHP and Java for years, and their documentation is
>> concise, well structured and easy to scan.
>
> Are you mad? Javadoc is one of the worst examples of sour
>
>>
>> Therefore, if you truly want changes in the documentation, I suggest that,
>> rather then whining to the group, you make some of the changes yourself.
>
> I agree up to here, with a different interpretation of the last clause.
> Work within the existing system. There are currently 250 o
On Wed, Nov 3, 2010 at 9:05 AM, Nizumzen wrote:
> Are you mad? Javadoc is one of the worst examples of source code
> documentation I can possibly imagine. I would go as far to say that the
> Python guys should do exactly the opposite of Javadoc.
For what it's worth, I concur.
cheers
James
--
On Nov 3, 7:43 am, Tim Harig wrote:
> On 2010-11-02, jk wrote:
>
> > As for the 9 paragraphs statement, there's a usability book that
> > applies here - it's called "Don't make me think". I shouldn't have to
>
> Anything that promotes a lack of thinking sends up red flags in my head.
> We want to
In message
, jk
wrote:
> This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
> about.
Framesets? Is that really your idea of well-laid-out documentation? Using a
feature which has been derided (and dropped in HTML5) because of its effect
on usability and accessibility?
--
http:/
On 2010-11-02 10:42:22 +, jk said:
Hi,
I've been coding in PHP and Java for years, and their documentation is
concise, well structured and easy to scan.
Are you mad? Javadoc is one of the worst examples of source code
documentation I can possibly imagine. I would go as far to say that th
On 11/2/2010 2:43 PM, Tim Harig wrote:
The real question is what do you want to gain by your posts here. You
should already know that most groups are, by their very nature, slow to
make changes to the status quo. The problem tends to be exasperated in
open source projects where any changes mea
On 03/11/10 05:04, John Nagle wrote:
>Right. Google does a far better job of organizing Python's
> documentation than the Python community does. I don't even try
> looking up anything starting at Python.org; I always start
> with a Google search. Even though Python.org's search is
> powered
On Nov 2, 2010, at 11:07 AM, Ian wrote:
> On 02/11/2010 14:47, jk wrote:
>> I think the key difference is that I don't want to have to *read*
>> the
>> python docs - I want to be able to scan for what I'm looking for and
>> find it easily. That makes me productive.
>>
> Hi jk,
>
> I totally a
On 11/2/2010 7:53 AM, Paul Rudin wrote:
Steven D'Aprano writes:
A fair point -- the built-in open comes up as hit #30, whereas searching
for open in the PHP page brings up fopen as hit #1. But the PHP search
also brings up many, many hits -- ten pages worth.
OTOH googling for "python open"
On Nov 2, 8:47 am, jk wrote:
> You're right in that the python docs in this case are less lines, but
> that's one of the problems. It doesn't mention anywhere the extra
> detail you've added regarding exceptions thrown. That's the kind of
> thing that probably comes through experience or some kind
On 2010-11-02, jk wrote:
> As for the 9 paragraphs statement, there's a usability book that
> applies here - it's called "Don't make me think". I shouldn't have to
Anything that promotes a lack of thinking sends up red flags in my head.
We want to recruit smart people who think, not idiots.
> go
On 02/11/2010 14:47, jk wrote:
I think the key difference is that I don't want to have to*read* the
python docs - I want to be able to scan for what I'm looking for and
find it easily. That makes me productive.
Hi jk,
I totally agree. But you will get nowhere.
A few weeks back I complained th
On 11/2/2010 6:42 AM, jk wrote:
Compare for instance the differences in ease of use, and speed of use,
of these:
http://docs.python.org/library/functions.html#open
http://uk.php.net/manual/en/function.fopen.php
The former is difficult to find (try searching for 'open' in the
search box and see
jk a écrit :
Hi,
I've been coding in PHP and Java for years, and their documentation is
concise, well structured and easy to scan.
Others have mentioned this apparently for years (see:
http://stackoverflow.com/questions/4046166/easy-to-navigate-online-python-reference-manual/4070851
and http://
Steven D'Aprano writes:
> A fair point -- the built-in open comes up as hit #30, whereas searching
> for open in the PHP page brings up fopen as hit #1. But the PHP search
> also brings up many, many hits -- ten pages worth.
>
OTOH googling for "python open" gives you the correct (for 2.7) pag
On Nov 2, 1:42 pm, Steven D'Aprano wrote:
> It's always difficult to know how much information is too much. The PHP
> docs seem to take an "everything including the kitchen sink" approach.
> Given that approach, it makes sense to divide everything into
> subsections, one page per function. But wit
On 2010-11-02, brf...@gmail.com wrote:
> A tutorial type book can also be great for reference and
> documentation (as long as its current). I would recommend a
> non-programmers tutorial to python even if you have started
> programming in other languages before. Also its a wiki book and is
> free
On Tue, 02 Nov 2010 03:42:22 -0700, jk wrote:
> Hi,
>
> I've been coding in PHP and Java for years, and their documentation is
> concise, well structured and easy to scan.
Well, that's one opinion.
> Others have mentioned this apparently for years (see:
> http://stackoverflow.com/questions/40
On Nov 2, 11:49 am, Tim Golden wrote:
> But why do you imagine that the core
> Python documentation -- developed and maintained by a group of people
> who clearly have some idea what they're doing -- should change to a
> format which happens to suit you?
It's not just me who's found the current d
On Tue, 2 Nov 2010 04:23:49 -0700 (PDT)
jk wrote:
> This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
> about.
>
> Why aren't the official docs like this, and why has it taken me 2 days
> of searching?
What's wrong with this:
http://docs.python.org/library/
?
If you have specific
On Tue, 2010-11-02 at 04:23 -0700, jk wrote:
> This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
> about.
Aaaarrr
> Why aren't the official docs like this,
Because not everyone likes documentation like that. Personally I far
prefer the existing documentation to the JavaDoc-s
A tutorial type book can also be great for reference and documentation (as long
as its current). I would recommend a non-programmers tutorial to python even if
you have started programming in other languages before. Also its a wiki book
and is free.
-Braden Faulkner
Sent wirelessly from my Bla
On 11/02/10 10:42, jk wrote:
Is there much chance that the Python maintainers will change their
documentation system to make it more like Java or PHP? How would I go
about trying to make that happen?
I am by no means an authority however since you ask it here I feel
compelled to give you my opi
On 02/11/2010 11:23, jk wrote:
This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
about.
Why aren't the official docs like this, and why has it taken me 2 days
of searching? All this needs is a search engine behind it and it'd be
perfect.
I'm glad you find the epydoc format usefu
This (http://epydoc.sourceforge.net/stdlib/) is what I'm talking
about.
Why aren't the official docs like this, and why has it taken me 2 days
of searching? All this needs is a search engine behind it and it'd be
perfect.
--
http://mail.python.org/mailman/listinfo/python-list
If you are really beginner in python you can look into the dive into
python,search as in google as the same its quite helpful for beginners.Also
you can go for the byte of python.
CHEERS
CNA
9986229891
On Tue, Nov 2, 2010 at 4:42 PM, jk wrote:
> Hi,
>
> I've been coding in PHP and Java for yea
37 matches
Mail list logo
