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

[Ian Bicking]

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
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 wouldn't mind having a prominent "External resources" page in the Python
> docs, if it is actively maintained and doesn't turn into a bunch of dead
> links in 12 months time. But I have grave doubts about linking to an
> external site all through the module documentation, no matter how useful it
> is. Who controls the external content?
>

Adding any content, including links, incurs extra maintenance for that
content.  Links are a little harder than other pieces, and they should be
added only with some consideration of the quality of the content.  Again,
conveniently, PyMOTW is a big list of quality documents, and AFAICT there is
widespread approval of the content.  Appropriate linking to some other
documents might also be quite helpful; adding PyMOTW makes it more likely
that will happen, but worrying about all the links we *aren't* adding
doesn't move anything forward at all.

Some tooling to manage the links would be nice, but doesn't seem like a
particularly big barrier -- a standard link checker would find dead links
(including existing external links) and there are tools to mirror content so
that if it's considered valuable and it really does disappear, we can
consider mirroring it (Wikipedia seems to do something roughly like this
with web-addressable citations).

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