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

[Alexander Belopolsky]

On Sun, Mar 20, 2011 at 9:18 PM, Brian Jones <bkjones at 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.