[Python-ideas] Linking Doug's stdlib documentation to our main modules doc.

[Jim Jewett]

On Sun, Mar 20, 2011 at 9:18 PM, Brian Jones <bkjones at gmail.com> wrote:

> On Sun, Mar 20, 2011 at 2:18 PM, Alexander Belopolsky
> <alexander.belopolsky at gmail.com> wrote:

>> I'll focus on criticism even though, overall I find the
>> PyMOTD:datetime page a good introduction to the datetime module.   I
>> would recommend this page to beginners, but probably *before* the
>> official docs, so a "see also" link is probably not the right way to
>> link PyMOTD pages.   Maybe a link to PyMOTD should be added to the
>> main docs.python.org page.

>> Now, what I don't like about PyMOTD:datetime.

>> 1. Order of presentation: time, date, timedelta, datetime, tzinfo.
>> For an introductory article, I would start with date, then do datetime
>> and timedelta.  The time objects are not that useful


> This is all just so ridiculous.
> If we're so sensitive to some (btw, arbitrary and subjective in this case)
> ordering, then why is the official stdlib documentation *not* in this order?

The order he recommended makes sense for a tutorial introduction.
Another order -- such as putting constants first -- makes sense for an
API reference.

He does say it would make sense to refer beginners to PyMOTD *before*
the official documentation; a see-also at the *end* of the official
module documentation won't do that.  (Adding it to a list of
alternative references at the beginning of the not-per-module
documentation *might*.)

-jJ