Dr. Dobb's Python-URL! - weekly Python news and links (Dec 2)

[BartlebyScrivener]

Re: Bitching about the documentation.. .

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

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

rd

[Paul Rubin]

Re: Bitching about the documentation.. .

Steve Holden <steve@holdenwe b.com> writes:[color=blue]
> 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.[/color]

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.

[Aahz]

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

In article <11p9kl1cm57dr7 b@corp.supernew s.com>,
Grant Edwards <grante@visi.co m> wrote:[color=blue]
>
>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).[/color]

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@pythoncra ft.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@yahoo.com]

Re: Bitching about the documentation.. .


"Paul Rubin" <http://phr.cx@NOSPAM.i nvalid> wrote:[color=blue]
> Steve Holden <steve@holdenwe b.com> writes:[color=green]
> > 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.[/color]
>
> 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.[/color]

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

[Paul Rubin]

Re: Bitching about the documentation.. .

rurpy@yahoo.com writes:[color=blue]
> Redhat's Fedora project seems to have a fairly well developed
> program for recruiting and encouraging writers.[/color]

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@yahoo.com]

Re: Bitching about the documentation.. .

<gene.tani@gmai l.com> wrote:[color=blue]
> rurpy@yahoo.com wrote:[color=green]
> > skip@pobox.com wrote:[/color][/color]
--snip--[color=blue][color=green][color=darkred]
> > > If you prefer the latest documentation, bookmark this page:
> > >
> > > http://www.python.org/dev/doc/devel/index.html[/color]
> >
> > 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.
> >[color=darkred]
> > > That's updated every few months, more frequently as new releases approach.[/color][/color]
>
> Well, the docs are what they are, I can find what I need.[/color]

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.
[color=blue]
> 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.[/color]

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.
[color=blue]
> So either spend a little money, buy the Nutshell and Cookbook, (or,[/color]

If one is required to buy a book to use free software, it is not
really free, is it?
[color=blue]
> look at dozens of books, and many excellent ones:
> http://www.amazon.com/exec/obidos/tg...311503-6360648[/color]

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.)
[color=blue]
> or spend some time, look at the 2 complete intro books published on the[/color]

I did. I thought they both were poor.
[color=blue]
> web, there's also:
>
> http://awaretek.com/tutorials.html
> http://www.vex.net/parnassus/
> http://directory.google.com/Top/Comp...ython/Modules/
> http://cheeseshop.python.org/
> http://the.taoofmac.com/space/Python/Grimoire
> http://dmoz.org/Computers/Programmin...ython/Modules/
>
> http://aspn.activestate.com/ASPN/Cookbook/Python
> http://python.codezoo.com/
> http://sourceforge.net/softwaremap/t...8&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/2...rn_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[/color]

That's a very good list and I will save a copy, thanks. But what
does it have to do with Python's documentation?
[color=blue]
> So i don't think you ca really say the lang spec, the VM and the dev
> environment in general are poorly documented.[/color]

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?

[François Pinard]

Re: Bitching about the documentation.. .

[Ben Finney]
[color=blue][color=green]
>> please study this form, carefully read the small print, fill it
>> properly and send the yellow copy at this address."[/color][/color]
[color=blue]
> ... "so that it can go with all the other requests I get at various
> times from various people".[/color]

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.
[color=blue][color=green]
>> Astonished, you just cannot believe what you hear. Life is so
>> short, you think, why one would ought to stand with such guys?[/color][/color]
[color=blue]
> Perhaps because you have asked them to do something that benefits you,[/color]

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.
[color=blue][color=green]
>> As the room is full of other interesting people, you happily move on
>> towards them.[/color][/color]
[color=blue]
> 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.[/color]

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

[Paul Rubin]

Re: Bitching about the documentation.. .

"BartlebyScrive ner" <rpdooling@gmai l.com> writes:
[color=blue][color=green][color=darkred]
> >>The solution is clear: the distro maintainers should require that all[/color][/color]
> 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.[/color]

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.
[color=blue]
> 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.[/color]

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.
[color=blue]
> 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.[/color]

I don't know about this.
[color=blue]
> Again, taking something like Bengt Richter's suggestion as just one
> example. To me the module docs are almost incomprehensibl e 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.[/color]

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.
[color=blue]
> 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.[/color]

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.

[Ben Finney]

Re: Bitching about the documentation.. .

rurpy@yahoo.com wrote:[color=blue]
> If one is required to buy a book to use free software, it is not
> really free, is it?[/color]

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

[Erik Max Francis]

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

Aahz wrote:
[color=blue]
> 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".[/color]

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

[Grant Edwards]

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

On 2005-12-06, Aahz <aahz@pythoncra ft.com> wrote:[color=blue]
> In article <11p9kl1cm57dr7 b@corp.supernew s.com>,
> Grant Edwards <grante@visi.co m> wrote:[color=green]
>>
>>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).[/color]
>
> To use a Panix in-joke, how old are you, anyway?[/color]

Hmm, let's see....

"Wasting Time on Usenet Since 1989"
[color=blue]
> 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".)[/color]

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

[skip@pobox.com]

Re: Bitching about the documentation.. .

[color=blue][color=green]
>> 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.[/color][/color]

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

[gene tani]

Re: Bitching about the documentation.. .


skip@pobox.com wrote:[color=blue][color=green][color=darkred]
> >> 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.[/color][/color]
>
> 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[/color]

Skip: good points

orig qvetcher: Well, I won't have time til, maybe early 2007 to debate
the meaning of "free software","offi cial 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)

[A.M. Kuchling]

Re: Dr. Dobb's Python-URL! - weekly Python news and links (Dec 2)

On 5 Dec 2005 14:10:00 -0800,
rurpy@yahoo.com <rurpy@yahoo.co m> wrote:[color=blue]
> 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"?[/color]

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

[A.M. Kuchling]

Re: Bitching about the documentation.. .

On Mon, 05 Dec 2005 20:56:50 GMT,
Bengt Richter <bokr@oz.net> wrote:[color=blue]
> 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.[/color]

"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