another docs problem - imp

[rurpy at yahoo.com]

Steve Holden wrote:
> rurpy at yahoo.com wrote:
[...snip...]
> Well, perhaps if you'd read the intro to the documentation (more
> carefully), or if you were more used to reading programming manuals,
> you'd quickly have recognised
>
>      [, path]
>
> as meaning precisely that the path argument is optional.

I did realize that. (And I have read enough other
programming manuals that reading more will not
affect my recognition of anything.)  The issue was
not the optionality of the argument, it was the
type of the argument when it was supplied.

[...snip...]

> So you think the docs should be changed if just *one* person can't
> understand them. Or maybe *two*? or *ten*?

I don't know how many people had trouble
with the text.  But there were some postings,
and the number of people is almost certainly
orders of magnitude larger than the number
that post.
I continue to think that the way I interpreted it
was valid, so it *is* ambiguous, even if most
people quickly disambiguate it correctly.  If
you accept that, it should be clarified even if
the number was *one*.

[...snip...]

> > How about
> > 1 - read some clear unambiguous documentation.
> > 2 - write the code and it works as described.
> >
> Excellent. So now you only have to fix the docs and that's what everyone
> will do from now on.
>
> > My grandfather used to own a hardware store.
> > He frequently said he took every customer
> > complaint very seriously.  "For every customer
> > who complains, there are a 100 that just take their
> > business elsewhere."
> > I wonder how many people had a problem with
> > this and lost time.  Not as extreme as my case,
> > maybe just rereading it a few times.  And of course
> > this particular piece of documentation  is not an
> > isolated instance.  If you are happy with the status
> > quo, if it is "good enough" fine.   I am not.
> >
> > ...snipped long anacdote about busses...
> >
> Clearly. So get your sleeves rolled up and provide a fix. Then you too
> will get your name in the Python documentation contributors' list.

I would be sufficient reward just to get good, clear,
complete accurate python docs.

> I agree that things that are difficult to understand could usefully be
> fixed. Since this is the open source world I'm unsure as to why you feel
> somebody else should fix it. It's also fairly obvious since you failed
> to find other complaints about this issue in your Google search that it
> isn't a frequent cause of complaint.

I never suggested someone else should fix it.  I am willing
to submit either a doc bug reports, or patches provided
that there is a reasonable chance it will result in a positive
change.  I am not willing to invest a lot of time summiting
things that are ignored or dumped in the bit bucket.  So
in part, my post here was to gauge the reaction to proposed
change.

Frequency of public complaints is a *lousy* criteria.  Very
few people are going to complain publicly, especially here
where suggestions that Python is not perfect are often met
with derision or silence. That was the whole point of the
grandfather story.