[Python-Dev] [Doc-SIG] that library reference, again (original) (raw)

Fredrik Lundh fredrik at pythonware.com
Sun Jan 8 15:09:14 CET 2006

Donovan Baarda wrote:

> No, it's a fundamental goal: to support light-weight generation of rendered > markup directly from source code, to enable simple tools (CGI scripts, etc) > to be able to render reference documentation.

Python is run-time interpreted, but I don't think we need its documentation to be.

Are you sure ?

help(help)

From the pythondoc/lib goal list:

Support tighter (and 2-way) integration between the library reference
and help tools (pydoc, help, inspect, etc) and documentation generators
(epydoc, pythondoc, etc).

"trivial" is a relative term.

When I say "trivial" in this context, I mean that any programmer should be capable of writing a Python tool that does some kind of basic processing of the source format from scratch. The easier it is to do this, the more likely it is that someone will come up with a new way to use the information ("Web 2.0", you know...)

As a some-times developer not really interested in writing documentation, I must admit I really like ReST. It looks like plain text, so I can write and use it as plain text, but it also can magically transform to other formats and look pretty good.

Lots of "looks like plain text if you squint" formats can produce output that looks pretty good.

The problem is semantics; I haven't seen any format that looks like plain text but provides the amount of machine-readable semantic information that we have today. And I want more semantics, not less.

I hate writing XML/HTML, and my only experience with LaTex was brief and painful too. If I was forced to choose, I'd probably pick LaTex even though I don't know it as well as XML/HTML (I'd rather face an unknown evil than that particular devil I know).

Familiarity breeds contempt ? We're not talking about well-formed XML here, nor 1996-era hand-rolled web sites. If you look at typical Java- Doc or PythonDoc markup, or the translated samples, you'll notice that the source code contains very few HTML tags.

(I seriously doubt that your problems with XML/HTML is the use of < in- stead of {...)

I'm not going to write docs for stuff I didn't write myself. I'm not going to submit patches to Javadoc, LaTex or XML/HTML, but I might post vague "change this to..." bug reports.

Writing good documentation is hard (which is why I prefer to leave it to others if I can), but fixing almost good documentation doesn't have to be /.../

Since I'm focussed on the library reference, I'm a lot more interested in the fixers than the essay writers. Give people a way to find things to fix, and a way to fix it, and they will.

> It's the workflow that's the real problem here, but you cannot fix the workflow > without fixing the markup.

I must say I disagree with this statement... changing the markup will not change the workflow at all, just shave 3-6 mins off the compile-test step. I don't do this enough to really know if that's worth it.

Do you think wikipedia would be what it is today if the edit/save process included a 3-6 minute "regenerate site" pass ?

Heck, I've discovered dozens of bogosities in the current library reference while working on the translation tools, and I have the sources and full SVN access, but I find that the overhead discourages me from doing anything about them ("maybe later"). I simply don't have time to fix anything but very minor typos within a standard 15-minute "let's improve python" time slot, and I sure don't think I'm unique in this respect.

More information about the Python-Dev mailing list