[PYTHON DOC-SIG] Documentation enhancements

[David Ascher]

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

I for one would want to make sure that we don't rush into something like
this without making sure that the product is high-quality.  I agree with
,I think it was you, Andrew, that the docs need a typesetting makeover at
the very least.  I also feel that the tutorial badly needs an overhaul --
right now most of the good stuff is in "and then we added ..." sections,
which gives the wrong impression.  I realize that the author of the
tutorial (GvR) is too busy, but I do think it's an important and needed
change...

BTW: the reason I think it's important to do a good job is that I think
this sort of product has a much bigger PR effect than one might think --
and first impressions count a lot.

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

The os/posix/etc. modules fall into that category as well.

> Regarding a printed version, what should be in it?  Probably the big 4

> 	* Documentation for the matrix extensions?  

I will update the Numeric tutorial a lot in the future -- it seems it'd be
a shame to rush it out the door when it's not ready for prime time.

--david


_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________