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

[skip]

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

 

[Ben Finney]

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.

 

[BartlebyScrivener]

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

 

[Paul Rubin]

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.

 

[Steve Holden]

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.

 

[BartlebyScrivener]

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]

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.

 

[Aahz]

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

 

[rurpy]

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

 

[Paul Rubin]

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.

 

[=?iso-8859-1?Q?Fran=E7ois?= Pinard]

[Ben Finney]

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

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.

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!

 

[rurpy]

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?

 

[Paul Rubin]

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.

 

[Ben Finney]

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.

 

[Erik Max Francis]

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?

 

[Grant Edwards]

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.

 

[skip]

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]

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]

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)

 

[A.M. Kuchling]

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