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

[Alexander Belopolsky]

On Tue, Mar 15, 2011 at 3:11 PM, Tarek Ziadé <ziade.tarek at gmail.com> wrote:
>
> As I told Doug during Pycon, I think it would be a good idea to link
> his PyMOTW pages to our modules documentation in docs.python.org so
> people have more examples etc.
>

I did not know about PyMOTW until now, so I visited a page on the
module that I am well familiar with, the datetime module.   On a
cursory review, I don't think PyMOTW adds much to an already rather
extensive docs.python.org documentation.  One section, "Combining
Dates and Times" struck me as not very clear.  It starts with an
example:

print 'Now    :', datetime.datetime.now()
print 'Today  :', datetime.datetime.today()
..

$ python datetime_datetime.py
Now    : 2008-03-15 22:58:14.770074
Today  : 2008-03-15 22:58:14.779804
..

Why would someone interested in combining dates and time would like to
know two subtly different functions that return current time in a
datetime object?  The surrounding text does not explain the difference
between datetime.now() and datetime.today().

Overall I am -1 on linking PyMOTW datetime page from datetime documentation.

I am sure there are instances when a PyMOTW is a valuable addition to
the "official" module documentation, but I think a decision to link it
should be made on a case by case basis by someone who would review
both the official and PyMOTW pages and decide that a link to PyMOTW
adds to the quality of documentation for a given module.