Bitching about the documentation...

[rurpy at yahoo.com]

<skip at pobox.com> wrote in message
news:mailman.1628.1133798275.18701.python-list at python.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.