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

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

Dec 5 '05 #3

skip

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

Dec 5 '05 #4

rurpy

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.

Dec 5 '05 #5

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

Dec 5 '05 #6

skip

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

Dec 5 '05 #7

rurpy

sk**@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.

Dec 5 '05 #8

rurpy

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

Dec 5 '05 #9

Peter Hansen

ru***@yahoo.com wrote:

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

Dec 5 '05 #10

rurpy

Peter Hansen wrote:

ru***@yahoo.com wrote:
sk**@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. :-(

Dec 5 '05 #11

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

Dec 5 '05 #12

> 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

Dec 5 '05 #13

skip

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

Dec 5 '05 #14

bonono

sk**@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.

Dec 5 '05 #15

skip

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

Dec 5 '05 #16

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

Dec 5 '05 #17

Aahz

In article <ma***************************************@python. org>,
<sk**@pobox.com> wrote:

Tim Peters? Read it no matter what the subject says.

A-men!
--
Aahz (aa**@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)

Dec 5 '05 #18

Aahz

In article <11**********************@g44g2000cwa.googlegroups .com>,
BartlebyScrivener <rp*******@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 (aa**@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)

Dec 5 '05 #19

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

Dec 5 '05 #20

Scott David Daniels

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
sc***********@acm.org

Dec 5 '05 #21

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

Dec 5 '05 #22

Bengt Richter

On 5 Dec 2005 10:53:36 -0800, aa**@pythoncraft.com (Aahz) wrote:

In article <11**********************@g44g2000cwa.googlegroups .com>,
BartlebyScrivener <rp*******@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

Dec 5 '05 #23

nick

"BartlebyScrivener" <rp*******@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: fd****@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)

Dec 5 '05 #24

John J. Lee

"BartlebyScrivener" <rp*******@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

Dec 5 '05 #25

rurpy

"Tony Meyer" <t-*****@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.

Dec 5 '05 #26

rurpy

"Tony Meyer" <t-*****@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.

Dec 5 '05 #27

rurpy

<sk**@pobox.com> wrote in message
news:ma***************************************@pyt hon.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.

Dec 5 '05 #28

Fredrik Lundh

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

Dec 5 '05 #29

rurpy

Fredrik Lundh wrote:

ru***@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 ;-)

Dec 5 '05 #30

skip

>>>>> "bs" == BartlebyScrivener <rp*******@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

Dec 5 '05 #31

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

Dec 5 '05 #32

Grant Edwards

On 2005-12-05, ru***@yahoo.com <ru***@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

Dec 6 '05 #33

> 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

Dec 6 '05 #34

Fredrik Lundh

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>

Dec 6 '05 #35

gene tani

ru***@yahoo.com wrote:

sk**@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...311503-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/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

So i don't think you ca really say the lang spec, the VM and the dev
environment in general are poorly documented.

Dec 6 '05 #36

Steve Holden

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/

Dec 6 '05 #37

François Pinard

[sk**@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

Dec 6 '05 #38

François Pinard <pi****@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.

Dec 6 '05 #39

skip

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 we*******@python.org.

Skip

Dec 6 '05 #40

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

Dec 6 '05 #41

Ben Finney

FranÃ§ois Pinard <pi****@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

Dec 6 '05 #42

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

Dec 6 '05 #43

sk**@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.

Dec 6 '05 #44

Steve Holden

Paul Rubin wrote:

sk**@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/

Dec 6 '05 #45

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

Dec 6 '05 #46

Steve Holden <st***@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.

Dec 6 '05 #47

Aahz

In article <11*************@corp.supernews.com>,
Grant Edwards <gr****@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 (aa**@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)

Dec 6 '05 #48

rurpy

"Paul Rubin" <http://ph****@NOSPAM.invalid> wrote:

Steve Holden <st***@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

Dec 6 '05 #49