[Python-ideas] Linking Doug's stdlib documentation to our main modules doc.
steve at pearwood.info
Sat Mar 19 02:48:48 CET 2011
Ian Bicking wrote:
> On Thu, Mar 17, 2011 at 8:47 PM, Steven D'Aprano <steve at 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
>> 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:
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:
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
More information about the Python-ideas