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

[Steven D'Aprano]

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
>>> 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