OpenSource documentation problems

[A.M. Kuchling]

On Wed, 31 Aug 2005 12:14:35 GMT, 
> I use dir() all the time; help() not so much. Typing help(help)
> shows:
>
>      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 the wrapper is so naive
user can just type 'help' at an interpreter prompt:

>>> help
Type help() for interactive help, or help(object) for help about object.
>>>

What additions to that string would you suggest?

> Three weeks ago, in trying to explain a point about Python's
> zlib module, I discovered that the doc was wrong.
>     http://groups.google.com/group/comp.lang.python/msg/20609fff71a2ed02

I don't think I'd change the Python docs to try to explain this, because I
have no confidence that we can get the details correct. BerkeleyDB, curses,
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 Environment".  

--amk