OpenSource documentation problems

[Terry Hancock]

On Tuesday 30 August 2005 02:32 am, 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:

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.

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.

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.

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

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

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 have NEVER seen a closed source application or programming
language that came with that much documentation and support.

OTOH, there are lots of poorly-documented third-party Python
modules (as in any language).  Zope is a particularly nasty
example -- though I think I understand some of the reasons 
behind that (rapidly changing API, poor interaction with doc
tools, etc).

F. Lundh's documentation for Python Imaging Library is excellent,
though.

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.

I don't know, maybe I just don't have high expectations out
of documentation.  I've certainly made do with far worse
documentation than Python has.

Cheers,
Terry


--
Terry Hancock ( hancock at anansispaceworks.com )
Anansi Spaceworks  http://www.anansispaceworks.com