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

[Steven D'Aprano]

Ian Bicking wrote:

> I guess I'd summarize your point here that you feel that collective
> ownership and maintaining of additional docs will lead to better quality
> than external and single-author documentation.

Not really -- I'm more concerned by the risk and loss of control by 
partial reliance on external docs.

I'm sure the risk is manageable, but it's easy to get caught up in the 
enthusiasm for a change and not make any provision for managing that 
risk until after something has gone wrong.


[...]
>> 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?
>>
> 
> Easy: we change the links!  Even if we have to remove them entirely and lose
> the content, in the meantime it will have done good.  

Of course we can change the links, but there will always be a lag 
between some hypothetical negative change occurring and the links being 
removed. First we have to notice the change, then we have to reach 
agreement that it is bad enough to remove the links (which won't 
necessarily be clear), and only then remove the links. In the meantime, 
what message are we sending?


> If it seems like a
> concern, maybe we can talk about licensing -- e.g., a nice CC license (I
> don't see a problem with non-commercial), with a gentleman's agreement that
> we not clone the content unless the author explicitly lets go or becomes
> unresponsive.  But such licensing is a detail we can consider later IMHO, it
> doesn't have any concrete effect now and we could look at it later if we
> start seeing a lot of external documentation and use of that documentation.

"If" it seems like a concern? We're having this debate because there 
*is* a concern.

I don't know that licensing is actually an issue. If we're just linking 
to an external site, do we care what the license of that content is? 
Perhaps we do -- Terry has already raised the issue that he's writing a 
book too, and would love (but doesn't expect) to have his content linked 
to the Python docs. Good quality links like that are worth real money. 
Nothing will poison a community faster than the idea that the 
organization is playing favourites, that some people are getting their 
commercial content advertised by python.org while others are excluded. 
That's a serious can of worms, and I don't think we should just gloss 
over this risk for the short-term benefit of gaining some nice 
documentation.

In the meantime, I note that on this page:

http://www.python.org/doc/

there is a section "Additional Documentation", which includes Richard 
Gruet's Python Cheat Sheet. I don't see any reason why we shouldn't link 
to Doug's site from there. If anyone is willing to champion the idea of 
more extensive linking, then I think it deserves a PEP.




-- 
Steven