<br><br><div class="gmail_quote">On Sun, Mar 20, 2011 at 2:18 PM, Alexander Belopolsky <span dir="ltr"><<a href="mailto:alexander.belopolsky@gmail.com">alexander.belopolsky@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
On Sun, Mar 20, 2011 at 12:07 PM, Alexander Belopolsky<br>
<div class="im"><<a href="mailto:alexander.belopolsky@gmail.com">alexander.belopolsky@gmail.com</a>> wrote:<br>
</div>..<br>
<div class="im">> Let me review that page more thoroughly.<br>
<br>
</div>I'll focus on criticism even though, overall I find the<br>
PyMOTD:datetime page a good introduction to the datetime module. I<br>
would recommend this page to beginners, but probably *before* the<br>
official docs, so a "see also" link is probably not the right way to<br>
link PyMOTD pages. Maybe a link to PyMOTD should be added to the<br>
main <a href="http://docs.python.org" target="_blank">docs.python.org</a> page.<br>
<br>
Now, what I don't like about PyMOTD:datetime.<br>
<br>
1. Order of presentation: time, date, timedelta, datetime, tzinfo.<br>
For an introductory article, I would start with date, then do datetime<br>
and timedelta. The time objects are not that useful and aware time<br>
objects are rather exotic since time method of datetime strips tzinfo.<br>
The first example exposes the reader to the tzinfo attribute of time<br>
objects without any explanation.<br></blockquote><div> </div><div>This is all just so ridiculous. </div><div><br></div><div>If we're so sensitive to some (btw, arbitrary and subjective in this case) ordering, then why is the official stdlib documentation *not* in this order? Why does the datetime module documentation not cover the actual class for which it is named until after things like timedelta? Why does the document start out by covering constants, follow with available types, then shove in a few completely random miscellaneous statements, and dive into the timedelta object? Is this *really* the best way to introduce the datetime module to someone new to the language? How does the standard documentation hold up to the criteria you're using to critique the PyMOTW documentation? Why is there so much energy put forth to squash a good idea and almost none toward doing the actual work to improve what's already there? If the standard documentation was really that awesome, this discussion may never have come up. Let's think about the bar we've set in the standard library docs, and consider how PyMOTW contributes to raising that bar. </div>
<div><br></div><div>The standard lib documentation is *not* all that awesome, *especially* for newcomers, in large part because large swaths of it are probably autogenerated direct from the source code. It therefore lacks almost any notion of human tone or personality, is completely unopinionated, dry, and in plenty of cases fails to document a given module completely. Where it does *document* completely, it doesn't necessarily provide examples illustrating the complete set of functionality provided by the module. Neither does PyMOTW, but the point is that they're complementary resources. </div>
<div><br></div><div>PyMOTW provides a "feel" for a module. The stdlib docs are really designed to be a reference. If they *weren't* designed to strictly be a reference, then they need more work than I thought. </div>
<div><br></div><div>Anyway, this critique is completely orthogonal to the issue at hand. What I think we're after here is: </div><div><br></div><div>1. Adding value over and above the standard library documentation</div>
<div>2. Targeting an audience (newbies or new-to-Python) that is just about completely ignored by the standard library documentation.</div><div><br></div><div>Do the PyMOTW documents, on the whole, add value over and above the standard library documentation? I have yet to hear any compelling argument that they don't.</div>
<div><br></div><div>Doug's existing 2.7-based work should be linked in the Python 2.7 documentation. This is not to say that this should happen to the exclusion of any other existing or future material by other authors. We already link to other external material, so it's not like there's no precedent for this. There's no precedent for the pervasiveness of the links being proposed, but that's because there's no precedent for a single work that so closely mirrors and deliberately targets full coverage of every module in the standard library. </div>
<div><br></div><div>Does the proposal represent perfection? Absolutely not. Perfection would involve an overhaul of the existing documentation, which in plenty of places sucks no matter what your experience with Python or programming in general. But even if that were to occur, I think Doug's work would still add value. </div>
<div><br></div><div>I move to stop playing Monday morning quarterback with Doug's work. There's no work that couldn't be better based on anyone's subjective idea of what "better" means. </div><div>
<br></div><div>I've been in the position in the past of editing Doug's work. I'm currently reviewing Doug's book. I've been a long-time reader and user of both the standard library docs and PyMOTW. I'm working on a book for O'Reilly *right now* that will compete *directly* with Doug's book. I have the capability and, some might speculate, a motive to rip Doug's work apart. Doing so, in my opinion, has no merit, hinders efforts to improve the overall experience of those new to the language, and attempts to hide a perfectly worthy collection of work from those in need. Further, when these people come to stackoverflow and say that they have a question not answered by the standard docs, we're all going to point them to PyMOTW anyway. </div>
<div><br></div><div>Doug's work is solid. Not perfect -- solid. It approaches topics in a reasonable way, provides a bit more humanistic tone and personality, covers the topics accurately, and does so for the entire standard library. If I weren't knee-deep in a book project of my own, I'd be happy to make this task my first commit ever to the Python documentation tree. If this thread continues until July, I just might be able to do that ;-)</div>
<div><br></div><div>brian</div><div><br></div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
2. In the first paragraph of the "Times" section: "the default of 0 is<br>
unlikely to be what you want" - this is somewhat confusing given that<br>
the following example is using the default value for microseconds and<br>
01:02:03 time which is equally unlikely to be what someone wants in a<br>
typical application. It looks like the "unlikely" comment was about<br>
time() with no arguments and default of 0 for all components. It<br>
would be better to use a "likely" example, preferably in the PM range<br>
so that the reader is gently introduced to the 24-hour system. For<br>
example, 5pm as a typical office closing hour would be good, or say<br>
5:45 pm as a realistic train departure time. Any of these would be<br>
better that a purely artificial time(1, 2, 3). </blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<br>
3. The min/max/resolution example. I don't think I ever used these<br>
attributes of the time class. Resolution is occasionally useful, but<br>
mostly for timedelta. Similarly, min and max of the other types<br>
reflect some non-obvious design choice, but for time, it is just the<br>
24 hours in a day range.<br>
<br>
4. The error passing float to microsecond argument example. Why are<br>
microseconds singled out? Similar error would result from passing<br>
float for hours, minutes or seconds. An example of how to generate<br>
and catch type error is not very helpful in an document about the<br>
datetime module. I would much rather see an example of how to convert<br>
fractional hours, minutes or seconds to datetime objects using<br>
timedelta constructor. (This is another case where dealing with time<br>
type is awkward because it does not support arithmetics. Another<br>
reason not to pick it as the first type to cover.)<br>
<br>
5. The now() and today() example that I criticized in my earlier post<br>
is still present in the "canonical" version. The text preceding that<br>
example says: "there are several convenient class methods to make<br>
creating datetime instances from other common values." However, this<br>
does not match the examples which immediately follow. I would expect<br>
to see datetime.fromtimestamp() in that section, but for some reason<br>
it is covered in the "Dates" section instead.<br>
<br>
6. In the revised "Time Zones" section, the author toned down his<br>
criticism of the approach taken by module developers. In the 2008<br>
version, he called the tzinfo situation "ironic." Still, this section<br>
does not provide any useful examples. At the very least, it should<br>
give an example of passing tzinfo to datetime.now() to obtain current<br>
time in an aware datetime object. For 3.2 such example could use the<br>
new timezone type, but for 2.x it would be appropriate to provide an<br>
example using either pytz or a sample tzinfo implementation.<br>
<br>
The datetime module is a difficult area to cover. As I said before,<br>
it is likely that the situation with the other modules is different.<br>
If maintainers of other modules think that their documentation will<br>
benefit from a PyMOTW link, I have no objection to that. I still -1<br>
on adding a PyMOTW:datetime link to the datetime module reference<br>
manual.<br>
<br>
I hope Doug will find my review of his datetime page helpful. I think<br>
PyMOTW will similarly benefit from other core developers' reviews as<br>
they consider linking PyMOTW to their documentation. However, blindly<br>
linking all pages simply because some people find Doug's work overall<br>
a better guide to stdlib than the official pages will only confuse<br>
readers. The reference manual and PyMOTW are two different works<br>
targeting different audiences. PyMOTW is more like a tutorial, trying<br>
to concisely introduce main features of each module without a claim to<br>
be comprehensive. In the reference manual on the other hand we try<br>
to be complete in feature coverage and economical in illustrative<br>
examples.<br>
<br>
It is reasonable to expect users to read PyMOTW articles in their<br>
entirety while reading entire sections of the reference manual would<br>
mean a very boring weekend. This observation makes it hard to find a<br>
good place for a PyMOTW? Should it go in the beginning or the end of<br>
the reference manual page? In either case, it is unlikely to be<br>
noticed by a typical user who goes directly to the class or method<br>
documentation through some kind of search.<br>
<div><div></div><div class="h5">_______________________________________________<br>
Python-ideas mailing list<br>
<a href="mailto:Python-ideas@python.org">Python-ideas@python.org</a><br>
<a href="http://mail.python.org/mailman/listinfo/python-ideas" target="_blank">http://mail.python.org/mailman/listinfo/python-ideas</a><br>
</div></div></blockquote></div><br><br clear="all"><br>-- <br>Brian K. Jones<br>My Blog <a href="http://www.protocolostomy.com">http://www.protocolostomy.com</a><br>Follow me <a href="http://twitter.com/bkjones">http://twitter.com/bkjones</a><br>