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

[Nick Coghlan]

On Sun, Mar 20, 2011 at 3:27 AM, Jesse Noller <jnoller at gmail.com> wrote:
> I don't agree with the hand waving around broken links, the fact the
> Doug wrote a book, endorsements, etc. The fact is, he's written better
> docs on many things, and we're doing the community a disservice by not
> actively exposing them as supplements to the existing documentation.
>
> Why is it so hard to simply do the right thing here?

Because it's a new idea and a level of
integration-without-incorporation that hasn't been considered before.
The PSF reps on here (along with everyone else) wouldn't be doing a
good job as stewards of the language if valid concerns were glossed
over without being given due consideration.

We may decide that given the specifics of the situation then including
direct links from the 2.7 documentation to the current 2.x specific
versions is an appropriate outcome. If Doug no longer wanted to
maintain them separately in the future, then they could be
incorporated at that point rather than having to do it up front
(ideally under a contributor agreement, since relying on the existing
CC license would mean that commercial entities like IDE vendors would
need to drop it when redistributing the Python documentation set).

The key point that I think distinguishes PyMoTW from most other
documentation resources is that even though it is also being published
as a book, the whole thing is available online under a Creative
Commons Attribution-NonCommercial-ShareAlike license. Linking to a
public resource like that is a *very* different prospect to linking to
something that isn't independently redistributable. The source code
for it all is also posted on github, so even if Doug were to abandon
the project and drop off the face of the planet tomorrow, the repo
could be cloned by a new maintainer.

PyMOTW also covers each module individually, and links back to the
relevant section of the official Python documentation*, something
which other online resources may not do.

For the reasons given above, I'm also +1 on including PyMoTW links in
a "See Also" block at the bottom of each module's documentation. There
are specifics at play here (as noted above) that distinguish this from
linking to arbitrary resources on the web. One advantage to doing this
systematically is that it can be done as part of the documentation
generation process, rather than needing to be maintained individually
in the source code of the documentation for each module.

Cheers,
Nick.

* I thought http://docs.python.org/2.x had been added as an alias to
allow stable external links to 2.x specific documentation, but neither
that or 3.x appear to be currently working.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia