On Tue, Mar 15, 2011 at 3:11 PM, Tarek Ziadé <ziade.tarek@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.