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

[Alexander Belopolsky]

On Sun, Mar 20, 2011 at 12:07 PM, Alexander Belopolsky
<alexander.belopolsky at gmail.com> wrote:
..
> Let me review that page more thoroughly.

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 and aware time
objects are rather exotic since time method of datetime strips tzinfo.
  The first example exposes the reader to the tzinfo attribute of time
objects without any explanation.

2. In the first paragraph of the "Times" section: "the default of 0 is
unlikely to be what you want" - this is somewhat confusing given that
the following example is using the default value for microseconds and
01:02:03 time which is equally unlikely to be what someone wants in a
typical application.  It looks like the "unlikely" comment was about
time() with no arguments and default of 0 for all components.  It
would be better to use a "likely" example, preferably in the PM range
so that the reader is gently introduced to the 24-hour system.  For
example, 5pm as a typical office closing hour would be good, or say
5:45 pm as a realistic train departure time.  Any of these would be
better that a purely artificial time(1, 2, 3).

3.  The min/max/resolution example.  I don't think I ever used these
attributes of the time class. Resolution is occasionally useful, but
mostly for timedelta.  Similarly, min and max of the other types
reflect some non-obvious design choice, but for time, it is just the
24 hours in a day range.

4. The error passing float to microsecond  argument example.  Why are
microseconds singled out?  Similar error would result from passing
float for hours, minutes or seconds.  An example of how to generate
and catch type error is not very helpful in an document about the
datetime module.  I would much rather see an example of how to convert
fractional hours, minutes or seconds to datetime objects using
timedelta constructor.  (This is another case where dealing with time
type is awkward  because it does not support arithmetics.   Another
reason not to pick it as the first type to cover.)

5. The now() and today() example that I criticized in my earlier post
is still present in the "canonical" version.  The text preceding that
example says: "there are several convenient class methods to make
creating datetime instances from other common values."  However, this
does not match the examples which immediately follow.  I would expect
to see datetime.fromtimestamp() in that section, but for some reason
it is covered in the "Dates" section instead.

6. In the revised "Time Zones" section, the author toned down his
criticism of the approach taken by module developers.  In the 2008
version, he called the tzinfo situation "ironic."  Still, this section
does not provide any useful examples.   At the very least, it should
give an example of passing tzinfo to datetime.now() to obtain current
time in an aware datetime object.  For 3.2 such example could use the
new timezone type, but for 2.x it would be appropriate to provide an
example using either pytz or a sample tzinfo implementation.

The datetime module is a difficult area to cover.  As I said before,
it is likely that the situation with the other modules is different.
If maintainers of other modules think that their documentation will
benefit from a PyMOTW link, I have no objection to that.  I still -1
on adding a PyMOTW:datetime link to the datetime module reference
manual.

I hope Doug will find my review of his datetime page helpful.  I think
PyMOTW will similarly benefit from other core developers' reviews as
they consider linking PyMOTW to their documentation.  However, blindly
linking all pages simply because some people find Doug's work overall
a better guide to stdlib than the official pages will only confuse
readers.  The reference manual and PyMOTW are two different works
targeting different audiences.  PyMOTW is more like a tutorial, trying
to concisely introduce main features of each module without a claim to
be comprehensive.   In the reference manual on the other hand we try
to be complete in feature coverage and economical in illustrative
examples.

It is reasonable to expect users to read  PyMOTW articles in their
entirety while reading entire sections of the reference manual would
mean a very boring weekend.   This observation makes it hard to find a
good place for a PyMOTW?  Should it go in the beginning or the end of
the reference manual page?  In either case, it is unlikely to be
noticed by a typical user who goes directly to the class or method
documentation through some kind of search.