On Sun, Mar 20, 2011 at 8:47 AM, Raymond Hettinger <raymond.hettinger@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). Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia