Terry Reedy wrote:

On 3/17/2011 7:19 PM, Senthil Kumaran wrote:

On Wed, Mar 16, 2011 at 05:35:41PM -0400, Doug Hellmann wrote:

As I told Doug during Pycon, I think it would be a good idea to
link his PyMOTW pages to our modules documentation in
docs.python.org so people have more examples etc.

Various people have written various docs showing Python by example. I do not think any one should be singled out in the docs. On the other hand, the wiki could have a PythonByExample page (or pages) with links to various resources.

What he said.

With all respect to Doug, do we really want to bless his website more than any of the other Python blogs, tutorials, etc. out on the Internet?

Bah humbug. If we could link stdlib docs to every good quality piece of coverage for that module then that would be great. It's not like someone else has been denied, or that we're giving Doug exclusive linking rights or something. It just happens he has written the most comprehensive and maintained set of docs, and so it would be bureaucratically rather easy to get a bunch more helpful links in the docs that will help people learn Python better. Frankly it doesn't matter if it's "blessed" as that doesn't incur any real benefit.

I wouldn't mind having a prominent "External resources" page in the Python docs, if it is actively maintained and doesn't turn into a bunch of dead links in 12 months time. But I have grave doubts about linking to an external site all through the module documentation, no matter how useful it is. Who controls the external content?

Adding any content, including links, incurs extra maintenance for that content. Links are a little harder than other pieces, and they should be added only with some consideration of the quality of the content. Again, conveniently, PyMOTW is a big list of quality documents, and AFAICT there is widespread approval of the content. Appropriate linking to some other documents might also be quite helpful; adding PyMOTW makes it more likely that will happen, but worrying about all the links we *aren't* adding doesn't move anything forward at all.

Some tooling to manage the links would be nice, but doesn't seem like a particularly big barrier -- a standard link checker would find dead links (including existing external links) and there are tools to mirror content so that if it's considered valuable and it really does disappear, we can consider mirroring it (Wikipedia seems to do something roughly like this with web-addressable citations).

Ian