On Fri, Mar 18, 2011 at 8:48 PM, Steven D'Aprano <span dir="ltr"><<a href="mailto:steve@pearwood.info">steve@pearwood.info</a>></span> wrote:<br><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">

<div class="im">Ian Bicking wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
On Thu, Mar 17, 2011 at 8:47 PM, Steven D'Aprano <<a href="mailto:steve@pearwood.info" target="_blank">steve@pearwood.info</a>>wrote:<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Terry Reedy wrote:<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
On 3/17/2011 7:19 PM, Senthil Kumaran wrote:<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
On Wed, Mar 16, 2011 at 05:35:41PM -0400, Doug Hellmann wrote:<br>
<br>
 As I told Doug during Pycon, I think it would be a good idea to<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
link his PyMOTW pages to our modules documentation in<br>
<a href="http://docs.python.org" target="_blank">docs.python.org</a> so people have more examples etc.<br>
<br>
</blockquote></blockquote></blockquote>
Various people have written various docs showing Python by example. I do<br>
not think any one should be singled out in the docs. On the other hand, the<br>
wiki could have a PythonByExample page (or pages) with links to various<br>
resources.<br>
<br>
</blockquote>
What he said.<br>
<br>
With all respect to Doug, do we really want to bless his website more than<br>
any of the other Python blogs, tutorials, etc. out on the Internet?<br>
<br>
</blockquote>
<br>
Bah humbug.  If we could link stdlib docs to every good quality piece of<br>
coverage for that module then that would be great.  It's not like someone<br>
else has been denied, or that we're giving Doug exclusive linking rights or<br>
</blockquote>
<br></div>
In that case, I nominate Michael Foord's documentation of urllib2 for linking as well:<br>
<br>
<a href="http://www.voidspace.org.uk/python/articles/urllib2.shtml" target="_blank">http://www.voidspace.org.uk/python/articles/urllib2.shtml</a><br>
<br>
I am serious, by the way, I think Michael's urllib2 docs are excellent.<br></blockquote><div><br>Certainly, it also seems very appropriate.<br><br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">


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."<br>


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

</blockquote><div><br>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.  I think with docs in particular this is difficult because the bureaucratic nature of collective ownership makes it hard to actually do the work to improve documentation, as it's hard to maintain a sense of voice and I think it's hard to maintain the willpower to write documentation in particular in the face of collectivist stop-energy.  And unlike the standard library itself, documentation does not suffer nearly as much from size -- the stdlib itself is conservatively maintained, but documentation could be much more freely maintained, and external links are one way of accomplishing that.<br>

<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
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.<br>


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


<br>
<a href="http://docs.python.org/library/xml.etree.elementtree.html" target="_blank">http://docs.python.org/library/xml.etree.elementtree.html</a><br>
<br>
othertimes it is implied, e.g. the Decimal docs say "See also" and then link to a pair of carefully selected (semi-)official sources.<br></blockquote><div><br>I don't think there is any significant authority incurred here, because the docs themselves are not authoritative.  Generally speaking if many people use something in the standard library that is not documented, it turns into a kind of precedence anyway -- so if Doug or anyone else documents something non-public in the standard library, it means that interface is going to have to be supported or at least thoughtfully deprecated.  That's true regardless of linking.<br>

<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
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.</blockquote>

<div><br>I... don't really get this.  I feel fine with this condition with respect to Doug's docs, but I don't see it as necessary anyway; there are good documents written by relatively unknown authors on specific topics.  I don't seriously fear those docs will be changed underneath our feet.  They probably *won't* be updated, and I have definitely noticed old Developer's Works articles that are distractingly out of date.  OTOH, linking to good things *helps*, because when you Google for something it's hard to separate the old from the new.  It adds us to the curation process.<br>

<br></div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;"><div class="im">
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
something.  It just happens he has written the most comprehensive and<br>
maintained set of docs, and so it would be bureaucratically rather easy to<br>
get a bunch more helpful links in the docs that will help people learn<br>
Python better.  Frankly it doesn't matter if it's "blessed" as that doesn't<br>
incur any real benefit.<br>
</blockquote>
<br></div>
I think you mean "cost".<br></blockquote><div><br>I mean benefit to the person we're linking to.  People are writing these things to help other people learn Python, they are acts of generosity, and any other benefits they might incur to the author are just a nice coincidence.<br>

<br> </div><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
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?<br>

</blockquote><div><br>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.  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.<br>

<br>There are some content management concerns, which would probably be good to think through.  It would be nice if links were tagged with what Python versions they describe because it is a realistic concern that things won't be updated (and already there's many things that aren't updated for Python 3, or will be forked documents in which case you'd want  both links in with different tags).  It would be even nicer if we had a little microformat for pages to self-describe versions.  It would be nice if there was a somewhat transparent link submission process, along with content guidelines; even if they are fuzzy guidelines like "a new link should add significant benefit over the content of the original documentation and any existing links" or "we strongly prefer documentation that has seen community acknowledgement and use".  Mostly expectation management for submitters.  External documents that themselves refer to other documents can be problematic, especially something like "a review of web frameworks" -- which might be nice to link to from wsgiref, but in a practical sense probably much too hard to maintain unless someone really wrote it to be timeless (which would be possible with the proper PyPI category links, wiki links, etc).<br>

<br>I don't feel like just linking to <a href="http://wiki.python.org">wiki.python.org</a> pages is a good idea, because all the problems with external links are also problems with wiki pages and generally wiki pages seem to end up worse -- more out of date, less well edited, more dead links, etc.  In theory they could be maintained better, but it's failed enough in practice to put me off (barring some serious rethinking of the wiki itself; like maybe a more Stack Overflow approach might be successful where a freeform editable page is not).  Also I don't think we'd see much traffic from the docs through to useful external resources if we have an interstitial wiki page.  And if people don't click through then we'll have neutered the point of the original proposal.<br>

<br>  Ian<br><br></div></div>