[Python-ideas] Linking Doug's stdlib documentation to our main modules doc.
ncoghlan at gmail.com
Sun Mar 20 00:50:20 CET 2011
On Sun, Mar 20, 2011 at 8:47 AM, Raymond Hettinger
<raymond.hettinger at gmail.com> wrote:
> P.S. I really like Doug's collected articles and find them
> to be a pleasure to read; however, the articles have
> a introductory survey quality to them and do not purport
> to be up-to-date or to be complete (many methods, flags,
> arguments, classes, are omitted), so I'm not sure how well
> they would serve as primary documentation.
It's precisely their survey quality that makes them a potentially
useful supplement to the existing documentation.
Jacob Kaplan-Moss gave an excellent talk at PyCon regarding the
multiple levels at which documentation needs to work. Most of the
module documentation in the Library Reference dives right in to API
level reference details, which can be impenetrable for users trying to
get a feel for an unfamiliar module. Not all of our documentation is
like that (plenty of people will have heard me talking up the new
logging tutorials Vinay added for 3.2), but quite a lot of it is.
Systematically linking to PyMOTW would be about providing new users
with a resource that may help them come to grips with a module when
using it for the first time, helping to fill the gaps where our own
documentation fails to cover this aspect.
All respect to Doug, while his opinion as the PyMOTW author is
certainly relevant, this question is about whether or not such links
would make the Library Reference documentation better for newcomers,
so the final decision certainly isn't his (if the final call belongs
to anyone other than Guido, it would be Georg).
Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia
More information about the Python-ideas