On Sun, Mar 20, 2011 at 1:52 PM, Alexander Belopolsky <alexander.belopolsky@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@gmail.com | Brisbane, Australia