another docs problem - imp

[Steve Holden]

rurpy at yahoo.com wrote:
> "Fredrik Lundh" <fredrik at pythonware.com> wrote in message
> news:mailman.306.1136963981.27775.python-list at python.org...
> 
>>rurpy at yahoo.com wrote:
>>
>>
>>>>from the find_module documentation:
>>>>
>>>>          find_module( name[, path])
>>>>
[...]
> 
> 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.
> 
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.
> 
>>... 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)
> 
Reliance on dictionary definitions is often the sign of rigid thinking. 
If you can't produce your own definition and defend it you'd probably be 
better of not quoting a definition in the first place.

> "few" has nothing to do with it.

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

> 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.
> 
As is your insistence on debating the point rather than submitting a 
change request via sourceforge.
> 
>>    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.
> 
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 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.

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/