Ian Bicking wrote:
On Thu, Mar 17, 2011 at 8:47 PM, Steven D'Aprano <steve@pearwood.info>wrote:
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
In that case, I nominate Michael Foord's documentation of urllib2 for linking as well: http://www.voidspace.org.uk/python/articles/urllib2.shtml I am serious, by the way, I think Michael's urllib2 docs are excellent. But are we sure we want to go down this path? It's neither practical nor desirable to fill the Python docs with links to every good quality external source, so in a very real sense, yes, others will be denied. If not now, at some point we're going to say "I'm sorry, your web site is really excellent, but we're not going to link to you." But that's not my main objection. We keep the bar high for inclusion in the standard library, and it shouldn't offend anyone. I'm sure people will cope with the disappointment of having their excellent tutorial or blog rejected for inclusion. I think that the real risk comes from the implications of linking to an external page from the docs. If you think that there are no such implications, then you will probably think that there is no downside to such links. I hope to persuade you that there are, and that they need to be considered before making this decision. Giving a list of "useful external resources" is a very different from linking to Doug's site repeatedly throughout the module docs. The Python docs are not some blog, where external links are posted for fun or for giving credit, nor is it Wikipedia where the external links are used as authority. The Python docs are the authority. If they link to an external page, it confers some level of authority and officialness to that external page. Sometimes we do so explicitly, e.g. we link to Fredrik Lundh’s Elementtree pages: http://docs.python.org/library/xml.etree.elementtree.html othertimes it is implied, e.g. the Decimal docs say "See also" and then link to a pair of carefully selected (semi-)official sources. But the proposal goes even further: it would link to Doug's site from nearly every page in the modules documentation. By linking to an external site in such an intimate fashion, I believe we would be giving a significant level of official standing to an external site that we don't control. We would be saying not just that the site is a useful site, but that it's such a great site, and a *trusted* site, that we link to it all throughout the official documentation. That says a lot, and we shouldn't be so blasé about saying it.
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 think you mean "cost". But there is a real cost as well as benefit: the cost comes as risk. I think you have misunderstood my point about who controls the external content. Dead links are the least risk, and the only one that can be managed automatically. We would be linking to pages that aren't controlled by us. We have no real control over whether the pages remain updated, or what content goes into those pages, or whether they get filled with advertising, or whatever. These are real risks -- even if you trust Doug implicitly, what happens if he gets hit by a bus and somebody else takes over his website? Elementtree excepted, when we take on a module or package and distribute it as an official part of the standard library, we expect the author to hand over official control to the PSF (even if practical control remains in the author's hands). Perhaps we should consider something similar for documentation. -- Steven