[PYTHON DOC-SIG] Documentation enhancements
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.) 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...) Are there other documents that should be included? Possibilities: * qua.tex * The man page for the Python interpreter * Documentation for the matrix extensions? PIL? Something else? * Is there Windows or Mac documentation that could/should be included? Andrew Kuchling amk@magnet.com http://people.magnet.com/%7Eamk/ Save the Gutenberg Project! http://www.promo.net/pg/nl/pgny_nov96.html _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________
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 _______________
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 _______________
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...
Yes, and yes... :-(
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.
Hmm, I'm not sure. We don't have a marketing organization like O'Reilly, and we'll probably mostly sell to people who already like Python but don't have the resources to print the docs themselves. So I don't think it will be a big PR item. --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 _______________
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.)
In this case, it might be possible to use technology -- we could ask the python-list readers (and tchrist, why not =) to email a list of terms they would want to an automatic email processing system which could remove duplicates -- it might yield some 'collective insight' -- I especially think that the input of novices is most useful for this kind of thing (assuming that the input of experts is included as a matter of course).
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.
Agreed -- I think that whoever added 15 pages to the Tkinter lifesaver would make a lot of people very happy (and I mean a little more than just Tk 4.x compatibility). Don't look at me -- I got a dissertation to write, and then some... --david _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________
Agreed -- I think that whoever added 15 pages to the Tkinter lifesaver would make a lot of people very happy (and I mean a little more than just Tk 4.x compatibility). Don't look at me -- I got a dissertation to write, and then some...
Working on it. A replacement, that is; it has happened a lot since 3.x... Fragments are available at the address below. Comments are welcome. Cheers /F (http://hem1.passagen.se/eff) _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________
-----BEGIN PGP SIGNED MESSAGE----- On Mon, 31 Mar 1997 23:22:44 -0500 (EST), da@maigret.cog.brown.edu writes:
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.)
In this case, it might be possible to use technology -- we could ask the python-list readers (and tchrist, why not =) to email a list of terms they would want to an automatic email processing system which could remove duplicates -- it might yield some 'collective insight' -- I especially think that the input of novices is most useful for this kind of thing (assuming that the input of experts is included as a matter of course).
Even better, some way for people to add concepts (and associated page references) that should be indexed. That would probably require a human editor, though. [A copy of the headers and the PGP signature follow.] Date: Tue, 01 Apr 1997 08:00:50 -0600 From: "Jeffrey C. Ollie" <jeff@ollie.clive.ia.us> In-reply-to: Your message of "Mon, 31 Mar 1997 23:22:44 EST." <Pine.SGI.3.95q.970331231740.26053A-100000@maigret> Subject: Re: [PYTHON DOC-SIG] Documentation enhancements To: doc-sig@python.org -----BEGIN PGP SIGNATURE----- Version: 2.6.2 Comment: AnySign 1.4 - A Python tool for PGP signing e-mail and news. iQCVAwUBM0EVFpwkOQz8sbZFAQE30AP/SN6p8NptFrx5BSfEfYJX8+WRV5Xr6LKb +ITP7w/ZVLnalUF8QgX3hdyonzF+FNI1mtvS3t8o93Y1DgZtsQwcJCUmp9uIYElr OBl2akoX6a7GkcDttdpI/h82MajBa79rRi8BTulLkSjF/z/NjUQqbB8gyfmXPbsN S8vfNtjb76U= =3Xox -----END PGP SIGNATURE----- -- Jeffrey C. Ollie | Should Work Now (TM) Python Hacker, Mac Lover | _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________
G. Berriz also suggested having a note at the start of the index: "If you notice omissions, please help save the world and drop a note to XXX@python.org", where XXX is some mail alias for Guido or an editor, or possibly XXX='doc-sig'. The Tkinter life preserver is something I hadn't thought of; how long is it? (Place reference to the Monty Python lifeboat sketch here.) However, if Frederik is revising it for inclusion in his book, O'Reilly would have to agree to allowing republication of those sections. Regarding the tutorial: the later sections seem to contain two sorts of items. Some are just informational ChangeLog-like things ("The Macintosh version is much more robust now." "The string module now has a capwords() function.") which can be cut out and put in another file, and others are actual language changes, which will need to be integrated into the text. Tutorial readers probably don't care about the interpreter's past history. Guido van Rossum wrote:
(In fact, some chapters of the library manual, e.g. the SGI and Mac specific parts, might be left out too.)
Good point. One might also wonder if the SGI-specific modules should be dropped from the distribution; Python isn't only (or even mostly) on SGIs these days, and time seems to be taking its toll on them---there's a more recent OpenGL interface, PIL for image processing...
So I don't think it will be a big PR item.
Ah, but the HTML documentation would also benefit from improvements, and that is highly visible. People may also lend the book to others when evangelizing. Andrew Kuchling amk@magnet.com http://people.magnet.com/%7Eamk/ Save the Gutenberg Project! http://www.promo.net/pg/nl/pgny_nov96.html _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig@python.org administrivia to: doc-sig-request@python.org _______________
participants (5)
-
Andrew Kuchling -
David Ascher -
Fredrik Lundh -
Guido van Rossum -
Jeffrey C. Ollie