On Mar 20, 2011, at 11:42 AM, Alexander Belopolsky wrote:
On Sun, Mar 20, 2011 at 2:33 AM, Nick Coghlan <ncoghlan@gmail.com> wrote:
.. but can anyone cite a case where PyMOTW is actually *that* wrong?
Didn't I do it in my first reply to this thread?
""" .. 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. """
Note that my "-1" is limited to linking from the datetime module documentation. Having not read any other PyMOTW pages, I have no basis to form an opinion on whether links to those other pages will improve reader experience.
The datetime module may be unique because it actually suffers from too much documentation rather than the lack of it. The official datetime documentation and its PyMOTW page are not complimentary. They cover the same material in different styles. Some users are better off reading just PyMOTW, others may prefer the official doc. I don't really see much incremental value from reading both.
Note that it looks like PyMOTW author intended his pages to be self-contained rather than a compliment to the official doc. There is no link from PyMOTW datetime page to http://docs.python.org/library/datetime.html.
PS: The PyMOTW datetime page is at http://blog.doughellmann.com/2008/03/pymotw-datetime.html.
PPS: I don't think the PyMOTW datetime page is current for 2.7. This page seems to be 3 years old and 2.7 have seen a few additions to the datetime module.
The canonical version of that page is http://www.doughellmann.com/PyMOTW/datetime/. You will find a link to the stdlib docs, as well as some other useful date-related docs and tools, in the "See also" section at the bottom of that page. If you are going to review the content page by page, please look at the versions of the articles under http://www.doughellmann.com/PyMOTW/ Doug