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

[Ian Bicking]

On Fri, Mar 18, 2011 at 8:48 PM, Steven D'Aprano <steve at pearwood.info>wrote:

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

Certainly, it also seems very appropriate.



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



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

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.



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


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.


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

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.



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

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

I don't feel like just linking to wiki.python.org 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.

  Ian
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20110319/b0372567/attachment.html>