OpenSource documentation problems

[Bryan Olson]

Terry Hancock wrote:
 > Bryan Olson wrote:
 >
 >>I don't see any need to look beyond Python for a good example of
 >>poor documentation.  Are there serious Python programmers who
 >>don't constantly struggle with errors and omissions in the doc?
 >
 > Uh, yes, actually.
 >
 > IMHO, the available Python documentation is, extremely helpful,
 > concise and accessible.  Maybe you aren't using all of it:

A plausible theory. I have some possibly-illustrative examples
of what I ran into within the last few weeks.

 > 1) Remember that any object or module you load will tell you
 > its contents with a dir() or give you automatically generated
 > documentation with help().  This documentation has the advantage
 > of being almost always accurate and up-to-date, even if it is
 > sometimes too brief and poorly explained.

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


 > 2) More in-depth documentation for the Python standard library
 > is available in the "Library Reference".  This covers everything
 > from built-in functions to fairly obscure modules that are nevertheless
 > in the Python library.

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

The Python standard library is certainly useful, but in my
opinion the bar is set too low.


 > 3) Questions about the functioning of the language are most accurately
 > resolved by trying them out in the interpreter. This is usually
 > faster than any documentation search.  Python's interpreter is extremely
 > friendly and easy to start up, so this is really easy to do.

Then how does one distinguish stable, supported services, from
incidental behavior that can change without notice?


 > 4) But if you want a more theoretical and explained version of the
 > language, there's always the "Language Reference".

Which is what steered me wrong on the behavior of slice objects:

   http://groups.google.com/group/comp.lang.python/msg/66014427182265b9

That one cost me a hours, mostly because when I my own code
misbehaves in certain cases, a language/doc bug is not my first
guess.


 > Between these 4 sources, I can resolve almost any question that
 > comes up about the core Python language.
 >
 > Somewhat more obscure applications are covered by the "Extending
 > and Embedding" document, and there are other documents and tutorials
 > either in your Python distribution (if you have a good one) or on
 > the http://www.python.org website).

Three days ago, I wanted to know how to call C from Python, and
the "Extending and Embedding" document told me:

     (I won't dwell on how to call the Python parser with a
     particular string as input -- if you're interested, have a
     look at the implementation of the -c command line option in
     Python/pythonmain.c from the Python source code.)

I got the Python source distribution, and couldn't find that
file. So I went to the CVS archive, and still couldn't find the
file. I don't think it exists. Had that doc just said nothing
about it, I probably would have found PyRun_SimpleString and its
siblings in a few minutes. I suspect the document is out of
date, as it also seems to teach the use of deprecated methods.

Whatever else one says about open-source documentation, keeping
it current is a major unsolved problem.


 > If you're really looking for cookbook examples, there are specific
 > websites to check for, though I usually just hit Google with a
 > few keywords.  And if all that fails you, you can always ask the
 > people on this list.

I'm with you on that. (I used to work for Google, where finding
the doc means eating the dog-food.) I find that for any popular
software, typing error messages into Google yields a better
results-to-effort ratio than trying to look them up in a manual.


 > I have NEVER seen a closed source application or programming
 > language that came with that much documentation and support.

I'm no fan of Microsoft, but in general, the Win32 API is far
better documented than is Python. (Just don't use the searching
facilities on the MSDev CD's to find the doc; Google it up.)

[...]
 > I also have to say, that as a module writer, Python's support
 > for self-documenting code or "literate programming" is excellent.
 > I'm really coming to appreciate the value of this.

Unfortunately, it's also full of traps.


-- 
--Bryan