[PYTHON DOC-SIG] Documentation enhancements
Guido van Rossum
Mon, 31 Mar 1997 22:42:28 -0500
> I've found a publisher who's somewhat interested in producing a
> printed version of the Python docs, though nothing is certain yet. In
> the knowledge that there may be a printed version of the 1.5 docs,
> what changes should be made?
> Gabriel Berriz made some excellent suggestions, where the priority is
> improving the index and adding cross-references from module to module.
> (For example, the rand module would also reference random.py and
> whrandom.py. Michael K. Johnson at Red Hat independently suggested
> the same improvement.)
I don't like writing documentation much, and indexing is the most
boring part of documentation :-( So any help here would be
appreciated. The best way to index, I've been told, is for someone to
make a separate pass over the complete text when it's finished.
(However, O'Reilly did this for PP and the resulting index in the
first printing is considered somewhat lacking by most.)
> Regarding a printed version, what should be in it? Probably the big 4
> should all be included: library, reference, extension manual, and
> tutorial. (Or can the tutorial be left out? I'd vote no, but...)
It should be in! Makes it more valuable by itself.
> Are there other documents that should be included? Possibilities:
> * qua.tex
No, no, no!
> * The man page for the Python interpreter
> * Documentation for the matrix extensions? PIL? Something
The Tkinter lifesaver, if someone can be bothered to upgrade it to Tk
4.x. I think NumPy and PIL are a bit too specialized.
(In fact, some chapters of the library manual, e.g. the SGI and Mac
specific parts, might be left out too.)
> * Is there Windows or Mac documentation that could/should be
Hmm, not sure. Probably a specialized audience that requires special
catering anyway. But maybe Mark Hammond has something to add and we
could increase the audience 10-fold this way.
--Guido van Rossum (home page: http://www.python.org/~guido/)
DOC-SIG - SIG for the Python Documentation Project
send messages to: firstname.lastname@example.org
administrivia to: email@example.com