OpenSource documentation problems
fakeaddress at nowhere.org
Wed Aug 31 21:57:00 CEST 2005
A.M. Kuchling wrote:
> Bryan Olson wrote:
>>I use dir() all the time; help() not so much. Typing help(help)
>> Help on _Helper in module site:
>> Type help() for interactive help, or help(object) for help
>> about object.
>>That strikes me as not-particularly-helpful. Surely it should at
>>least direct the user to 'pydoc.help'.
> help *is* pydoc.help, or at least a trivial wrapper around it, so I don't
> see the purpose of mentioning that.
The purpose of mentioning it would be to, well, to tell the
> What additions to that string would you suggest?
Since "help *is* pydoc.help, or at least...", the call could
show the same thing as help(pydoc.help), or at least inform the
user that more of the story is available from help(pydoc.help).
>>Three weeks ago, in trying to explain a point about Python's
>>zlib module, I discovered that the doc was wrong.
> I don't think I'd change the Python docs to try to explain this,
How about to fix the error?
> because I
> have no confidence that we can get the details correct. BerkeleyDB,
> and the 'os' module pose similar problems. For example, people sometimes
> ask for more detail about POSIX functions, but no one wants to write a
> Python-specific version of "Advanced Programming in the Unix
Options include copying doc from zlib.h, or telling the user to
look up the flags in the real doc.
More information about the Python-list