Documentation suggestions

[Ian Bicking]

Fredrik Lundh wrote:
> > > There's another struggle within the LibRef: is it a reference or a
> > > tutorial?  Does it list methods in alphabetical order so you can look
> > > them up, or does it list them in a pedagogically useful order?  I
> > > think it has to be a reference; if each section were to be a tutorial,
> > > the manual would be huge.  Here I think the solution is to encourage
> > > separate tutorials and HOWTOs, and link to them from the LibRef.
> >
> > We don't have a clear place to put that material.  People's personal
> > pages leave the potential for material disappearing
>
> so ?  this "if we don't own it, we won't even pretend it exists" attitude
> of the PSF is beginning to get a bit boring.

Well, I ain't the PSF, so my comment here doesn't really indicate
anything with respect to that.  There are already links in the
reference document to external documents.  But if we start getting a
half dozen links for each page (which is not an unreasonable number)
the maintenance of trimming dead links and pages that are out of date
becomes more significant.  And there's no particular coordination, or
any simple feedback process that can be applied to all content.

I don't think there should be any policy discouraging external links;
there's a lot of sources like the Python Cookbook, some free online
books (e.g., Dive Into Python, or Think Like A Computer Scientist), and
stable personal pages that should be linked in .  But I do think that
we should encourage some specific process for new or revised
tutorial/howto contributions, like encouraging people put such material
in the wiki.  

  Ian