suggestions for more docs (was Re: Bug fix releases)

[Grant Griffin]

Guido van Rossum wrote:
> 
...
> But I understand that you're saying that the community has grown so
> conservative that it can't stand new features even if they *are* fully
> backwards compatible.
> 
> I wonder, does that extend to new library modules?  Is there also
> resistance against the growth there?  I don't think so -- if anything,
> people are clamoring for more stuff to become standard (while at the
> same time I feel some pressure to cut dead wood, like the old SGI
> multimedia modules).

As somebody who has sometimes fussed over certain new language features
(because they can make Python harder for beginnners to read, IMHO), I
can say that, nonetheless, I'm _absolutely_ in favor of more standard
library modules.

Although Python's beautiful simplicity makes "learning" it in an
afternoon possible, there's no avoiding the fact that learning its large
standard library (or even just the most important half-dozen or so
modules--if only the beginner were told which ones <hint>) will
inevitably take awhile.  I've been at Python for about a year now, and
having once "learned" it in an afternoon (in a day, actually--I'm a slow
learner <wink>), it's taken the rest of the year for me to get halfway
good at it.  Much of that has to do with the standard library.

Anyway, since mastering a large library is inevitable, we might as well
lay back and enjoy it.  (And presumably, the larger the library is, the
more likely we are to enjoy it. <wink>)

> So that relegates us at PythonLabs to a number of things: coding new
> modules (boring), or trying to improve performance of the virtual
> machine (equally boring, and difficult to boot), or fixing bugs (did I
> mention boring? :-).
> 
> So what can we do for fun?  (Besides redesigning Zope, which is lots
> of fun, but runs into the same issues.)

>From the preceeding, I'm gonna deduce that the primary excitement the
PythonLabs team gets is implementing new language features.  But what
about writing more documentation?--*that's* pretty exciting!  In fact,
as one who publishes software myself, I can attest to the fact that it's
even _more_ exciting than implementing new features. <wink>

Luckily, new features inevitably require new documentation, so indulging
in the former becomes an excuse to indulge in the latter.  But who
really needs an excuse?  When the PythonLabs team needs to let their
brains cool off after a hard day of doing boring stuff, they might treat
themselves to writing some of the following:

- Tutorial, Part II: This would be directed at people who have practiced
Python for, say, 3 months.  It would introduce them to the Python's more
features that aren't covered in the original tutorial.  It would be
written using examples (ala K&R), which would give a sense not just of
"what and how" but more of "when and why".

- A Tour of The Standard Library: This would help beginners learn the
most important standard modules--in effect, clearing the forest of its
useful (but less used) trees.  I really think that listing the most
frequently used modules (and the most important functions _in_ those
modules) would be a _great_ service to beginners.  Off the top of my
head, they might be (in no order): string, os, os.path, sys, math, re,
etc.  (Even just providing a _list_ of these things in order of
importance would be a great service, though, admittedly, that wouldn't
provide the PythonLabs team with more than a couple of hours of
excitement. <wink>)

Also, the following are available online, but including them in the
standard distribution would help beginners a lot: 

- Python Idioms: Why should "while 1:" remain a Masonic handshake known
exclusively to us "veterans"? <wink>

- FAQs: New Pythoneers often wonder "why is there no do/while?" and "why
do we have lists _and_ tuples?".  By providing FAQs in the standard
distribution, it would be a lot easier for them to learn answers to
these things, once somebody on c.l.py had told them to "read the fine
manual".

i'd-write-this-stuff-myself-but-writing-for-dspGuru-gives-me-as-much
   -excitement-as-my-cardiovascular-system-can-stand-<wink>-ly y'rs,

=g2
-- 
_____________________________________________________________________

Grant R. Griffin                                       g2 at dspguru.com
Publisher of dspGuru                           http://www.dspguru.com
Iowegian International Corporation            http://www.iowegian.com