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

[Nick Coghlan]

On Sun, Mar 20, 2011 at 1:52 PM, Alexander Belopolsky
<alexander.belopolsky at gmail.com> wrote:
> How?  Instead of "pervasive linking"  add a link to a "See also"
> sections of the modules for which PyMOTW in the opinion of the editor
> (meaning committer who adds the link) is a valuable addition to the
> official documentation.  Note that this is the same approach as we
> currently take with respect to source code links.  We don't add them
> pervasively, but only in cases when the source code is deemed useful
> to the target audience.

There's a huge difference between linking to source code (which may or
may not be edifying when it comes to respecting current Python idioms)
by default, and linking to well written documentation.

Having a mechanism to say "please don't automatically link to PyMOTW
for this module, I really, really don't like it and think it will
actively harm anyone attempting to understand how best to use this
API" may make some sense, but can anyone cite a case where PyMOTW is
actually *that* wrong?

To those who see these links as a bad idea, who are you afraid it will
hurt? We have an immediate target audience that we think it will help:
new Python users that will read the docs and follow the links there.

>From those opposing it I've heard objections along the lines of...

1. Why endorse Doug's take on the standard library over that provided
by a multitude of other authors (such as Dive into Python, Python
Essential Reference, etc)?

PyMOTW is unique (as far as I am aware) as it is structured the same
way as the Library Reference (i.e. with per-module documentation),
reasonably comprehensive (although it does leave out some of the more
obscure modules, such as binhex) and released under a permissive CC
license that allows independent redistribution (albeit not by
commercial entities).

That's a hugely valuable resource that has been made available for
free, and we'd be doing our users a service by linking to it more
prominently than just providing a single link in an irregularly
maintained and unpublicised list of additional resources [1] that
isn't even available through the official documentation on
docs.python.org.

2. What about link rot and obsolete material?

PyMOTW has an active maintainer in Doug Hellman who posts the source
as a github project (under the aforementioned permissive license). If
these become a problem, either the links can then be dropped from new
versions of the documentation, or else the project can be forked by a
new maintainer. I would personally hope that if Doug tired of
maintaining the project at some point in the future, he would be
willing to turn it over to PSF stewardship under the same licensing
terms as the rest of the documentation, but that possible scenario
isn't an argument against adding the external links for the benefits
of users *now*.

While I've tried to resist making any argument based on the specifics
of *who* Doug is rather than what he's written, people should be aware
that we aren't talking about a random person who happened to post some
good free information on the internet here: we're talking about the
current Communications Officer for the PSF [2]. I can understand his
reasons for wanting to maintain personal editorial control over
PyMOTW, so linking rather than embedding is the next best option when
it comes to serving users' interests. (Note that embedding under the
existing CC license would not only be disrespectful of Doug's wishes,
it would also cause a real redistribution licensing problem for the
many commercial entities that pass the Python documentation along to
their users, including Linux vendors, IDE vendors, etc)

Cheers,
Nick.

[1] http://www.python.org/doc/ (bottom of the page)
[2] http://www.python.org/psf/members/

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