OpenSource documentation problems

[Paul Boddie]

Xah Lee wrote:
> The "Language Reference" section (subtitled "for language
> lawyers") needs to be replaced by human-readible descriptions of
> Python's functions. For exapmle, in the style of official Java doc
> (http://java.sun.com/j2se/1.4.2/docs/api/index.html).

Nope. The Java documentation you're referring to corresponds to the
"Library Reference" in Python, which is a collection of human-readable
descriptions of Python's functions (whether you like them or not).
Meanwhile, the corresponding Java documentation for Python's "Language
Reference" is this document collection:

http://java.sun.com/docs/books/jls/second_edition/html/jTOC.doc.html

You'll notice that it resembles the Python documentation rather
strongly. I'm afraid that the "Computer Science Pretension" is
necessary with that kind of documentation so that "language lawyers" -
ie. people implementing compilers, runtimes, tools - don't create
something that doesn't work with genuine specimens of the language.

Now, I don't doubt that Python's documentation could be improved, and
I'm willing to improve it (and have improved it in the past). I even
ticked the box on some feedback form at EuroPython to say that I'm
willing to write Python docs. In fact, I may start looking at the
documentation tasks on the Wiki and seeing what I can contribute,
possibly from stuff I've already written but which doesn't trivially
slot into the documentation as it is today. And I don't disagree with
you that the PythonInfo Wiki is a structural mess (I can never manage
to navigate from the front page to the WebProgramming page, although I
obviously know the name of the page and don't need to, but this isn't
going to help someone who doesn't know that it's there), nor do I
disagree with you that TeX isn't exactly the most accessible
technology.

However, I would recommend that in order to be taken more seriously you
tone down the rhetoric, review the available documentation (including
stuff like "Dive Into Python" http://www.diveintopython.org/) and note
the actual purpose of that documentation (eg. language vs. library
reference) before suggesting the replacement of one text with another
that already exists.

> (in this respect, similar to how wikipedia's texts drift into a form of academic
> esoterica whose educational value and readibility are greatly reduced
> to the general public.)

And here's an example of that rhetoric I referred to. Personally, I
find Wikipedia very readable even for my increasingly shortening
attention span, and some academics would presumably argue that
Wikipedia has already crossed some kind of line of compromise between
accessibility and thoroughness. If you want things like the 1707 Act of
Union (http://en.wikipedia.org/wiki/Act_of_Union_1707) explained to you
without "esoterica", perhaps that says more about you than it does
about Wikipedia.

Please note that I'm not labelling you as a troll. As far as I can
tell, many of your ideas are fairly sound; it's just that it's hard
work to see past the rhetoric and posturing, which is a shame because
you quite possibly have a lot to contribute.

Paul