another docs problem - imp

Fredrik Lundh fredrik at pythonware.com
Wed Jan 11 02:19:24 EST 2006


rurpy at yahoo.com 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.

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


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

    1 - I think I know how this works
    2 - oh, it didn't work.  let's check the documentation
    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.
    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.

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.

crowd is not on the list.

This reminds me of the old story when the local bus company made it
possible to pay with special "bus cards", which works like this:

    1 - enter the bus
    2 - put your card in the card reader slot
    3 - if the card reader beeps annoyingly and flashes red, talk to
        the driver.  otherwise, get your card and get seated.

and some local rurpy's wrote long letters to the editor arguing that it
was a disgrace that the bus company didn't publish more information
in advance; maybe an illustrative folder sent to everyone in the area
would have been a nice idea, or some television spots showing how
to put the card in the reader?  The reply from the bus company was
a gem:

    "it's really very simple, and you only have to learn this once"

It may have taken you two hours, but now you know that strings are
sequences too, and that you cannot treat a number of if-sentences or
can be-sentences in a piece of text as "what I originally thought *plus*
what it says."

The latter is likely to save your many hours in your continued career as
a professional (no matter what your profession really is).

</F>






More information about the Python-list mailing list