Steve Holden wrote: > [EMAIL PROTECTED] 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. -- http://mail.python.org/mailman/listinfo/python-list
