[Python-ideas] Linking Doug's stdlib documentation to our main modules doc.
jnoller at gmail.com
Mon Mar 21 00:05:20 CET 2011
On Sun, Mar 20, 2011 at 2:18 PM, Alexander Belopolsky
<alexander.belopolsky at gmail.com> wrote:
> 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
> 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
> 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.
Let me flip this around Alexander: If you completely rewrite the
datetime module's documentation - since I disagree with your
non-narrative, or non-example driven documentation and the order in
which you present various things, I *might* consider linking to it,
even if *it might* be a useful resource to introductory developers.
I thought adding things to the docs (one of the reasons I asked we
give Doug commit rights) might be a simple, easy or lower-argument
task. I see now I was wrong - almost perversely so.
More information about the Python-ideas