Re: another docs problem - imp
- From: rurpy@xxxxxxxxx
- Date: 12 Jan 2006 16:00:36 -0800
"Fredrik Lundh" <fredrik@xxxxxxxxxxxxxx> wrote in message
news:mailman.306.1136963981.27775.python-list@xxxxxxxxxxxxx
> rurpy@xxxxxxxxx wrote:
>
> > > from the find_module documentation:
> > >
> > > find_module( name[, path])
> > >
> > > Try to find the module _name_ on the search path _path_.
> > > If _path_ is a list of directory names, each directory is
> > > searched for files /.../. Invalid names in the list are
> > > silently ignored (but all list items must be strings).
> > > If _path_ is omitted or None, the list of directory names
> > > given by _sys.path_ is searched /.../
> > >
> > > it's not obvious how anyone can interpret the alternatives "a
> > > list where all items are strings / omitted / None" as "not a hint
> > > that a list is expected" and "a single string *should* work (i.e.
> > > be treated as a pathname, rather than a sequence)".
> >
> > Well, I interpreted the if's as describing special cases
> > addtional to the first sentence.
>
> The first sentence says that the _path_ argument is a search path.
> It does not say that it can be a string; that's something you made
> up all by yourself.
Correct it does not say it's a string. But your implication that
one can therefore conclude that it is not a string is silly.
>>From unittest:
> assert_( expr[, msg])
> failUnless( expr[, msg])
> Signal a test failure if expr is false; the explanation for the error
> will be msg if given, otherwise it will be None.
I should conclude that msg is not a string because
it doesn't say it is a string?
> > May I suggest that the problem is easily fixed simply
> > by removing the first "if".
>
> Like
>
> Try to find the module _name_ on the search path _path_.
> _path_ is a list of directory names, each directory is searched
> for files.
>
> ? So what happens when pupry reads this, and gets annoyed that he
> always has to pass in a list ? It's probably better if you learn to read
> technical documentation a bit more carefully.
Reading more carefully is always useful. But that does
not remove the obligation of the writer to write clearly and
unambiguously. Why would pupry think s/he always has
to pass in a list when the syntax description clearly shows
the arument is optional, and the following "if" sentence states
it is optional? But perhaps you are right; perhaps something
like "_path_is a optional list of..." would be clearer.
> ... and don't give me any "you're defending the status quo" crap in
> response to this. There are lots of things to do in the library reference,
> and a few of us are working on it (using different approaches), but
> trust me, optimizing for a few
"optimize": to make as perfect, effective, or functional as possible.
(Merriam Webster New Collegiate)
"few" has nothing to do with it.
If this required a huge amount of work, your resistance
would be understandable. Since the wording changes
are petty minor your flamage over this is puzzling.
> 1 - I think I know how this works
Wrong, I had no idea how it worked and read the docs
first.
> 2 - oh, it didn't work. let's check the documentation
Yes, read it a second time, didn't see the alternate interpretation.
> 3 - I think I've found a way to interpret the documentation as if
> it allows me to do what I'm doing. it doesn't explicitly say that
> I can do this, but it doesn't explicitly rule it out either, so I'm
> probably right. I'll try again. maybe it works this time.
Nope. It was "hmm, seems to clearly state that it
takes a path argument." Since I was dealing with a
single directory, and (this stuff dealing with imports
and all) had just before been thinking about sys.path
solutions, I was primed to accept that the argument
was a string and assumed I must be doing something
wrong." <later> "Is there any source? Nope
must be C." <later> "How about google". Oh here
is someone with same problem, Damn, no answer.
Ohh here is some one else, different problem but
he tried both find_module(..,"xxx") and (..,"[xxx]")
and the latter didn't generate the error message.
> 4 - (2 hours later) maybe I should try one of the alternatives that
> is mentioned in the documentation. oh, it did work if I follow the
> instructions. now I'm REALLY pissed, and am going to spend
> another hour arguing about this on the internet.
No. As I said, I did not see your way of interpreting the
documentation until you posted. And I had no plans
to argue about it. I posted for the reasons I gave,
and made a suggestion about how the documention
could be improved.
Well, in your attempt at mind reading you at least
got one out of four.
> practitioners, over the
> 1 - I think I know how this works
> 2 - oh, it didn't work. let's check the documentation.
> 3 - it says "can be a list" or "can be omitted". let's try one of
> those. oh, it worked.
How about
1 - read some clear unambiguous documentation.
2 - write the code and it works as described.
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...
.
- Follow-Ups:
- Re: another docs problem - imp
- From: Steve Holden
- Re: another docs problem - imp
- From: Fredrik Lundh
- Re: another docs problem - imp
- References:
- another docs problem - imp
- From: rurpy
- Re: another docs problem - imp
- From: rurpy
- Re: another docs problem - imp
- From: Fredrik Lundh
- another docs problem - imp
- Prev by Date: Re: Can't compile
- Next by Date: Conditionals stored as text to translate to real compares
- Previous by thread: Re: another docs problem - imp
- Next by thread: Re: another docs problem - imp
- Index(es):
Relevant Pages
|
