On Sun, Mar 20, 2011 at 9:18 PM, Brian Jones <bkjones@gmail.com> wrote: ..
This is all just so ridiculous. 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?
One possible explanation is that it was not written by me. :-) Seriously, official datetime documentation can be improved. Order of presentation is one area of improvement. Note that the order in "Available Types" is different from the order of per-type sections. I would certainly make sense to use the same somehow logical order for both. However, for a reference documentation that is not designed to be read sequentially, the order of presentation is not as important as in a module overview or a tutorial.
Why does the datetime module documentation not cover the actual class for which it is named until after things like timedelta?
I don't know. In the summary section the timedelta is listed after datetime. On the other hand, covering timedelta first, is likely to reduce the number of back-references because timedelta arithmetics is self-contained while datetime arithmetic properties cannot be described without introducing 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?
Constants followed by types is a fairly standard order in stdlib documentation. I think we mostly follow the order in which things are defined in code which in turn usually organized so that things are defined before they are referenced. What "random miscellaneous statements" do you refer to? Documentation patches are always welcome.
Is this *really* the best way to introduce the datetime module to someone new to the language?
No. Reference manual is *not* the best way to introduce anything to someone new to the language. We do try to make the reference manual novice friendly as long as it does not conflict with completeness or accuracy.
How does the standard documentation hold up to the criteria you're using to critique the PyMOTW documentation?
I would not use the same criteria for the two works. They serve different purposes.
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?
Why do you think adding a link to official module documentation pointing to a document that has not been reviewed by module maintainers is a good idea? ..
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.
I don't know about "on the whole." I have specific issues with the datetime article. Other modules' maintainers may or may not have issues with the specific PyMOTW articles. Why does this need to be all or nothing? Note that we don't cross-reference official tutorial sections from Language Reference. PyMOTW looks like the missing Library Tutorial. I don't object to featuring it as such on the main documentation page.