OpenSource documentation problems

[Bryan Olson]

A.M. Kuchling wrote:
 > Bryan Olson wrote:
 >
 >>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 mentioning it would be to, well, to tell the
user.

[...]
 > 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.
 >>    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,

How about to fix the error?

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

Options include copying doc from zlib.h, or telling the user to
look up the flags in the real doc.


-- 
--Bryan