[PYTHON DOC-SIG] Documentation enhancements

[Guido van Rossum]

> 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

Yes.

> 	* Documentation for the matrix extensions?  PIL?  Something
> else? 

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
> included?

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: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________