[Python-ideas] Linking Doug's stdlib documentation to our main modules doc.
orsenthil at gmail.com
Sat Mar 19 03:17:28 CET 2011
On Sat, Mar 19, 2011 at 12:48:48PM +1100, Steven D'Aprano wrote:
> In that case, I nominate Michael Foord's documentation of urllib2
> for linking as well:
> I am serious, by the way, I think Michael's urllib2 docs are excellent.
Already done! :)
But there is a difference. Do you see it is adopted as a howto under
python docs itself and undergoes similar maintenance as any other
document. We had fix some examples in there a couple of times.
I can understand case which Steven is putting forth and I tend to
agree with that. Linking an external resource at various places
consistently (like a footnote in every module doc) is kind of a
deviation from our current practise, there are chances of it getting
backfired with unforeseen scenarios later. (A possible case is if the
external resource undergoes a lag in maintenance and docs get updated
more frequently?) There is case in hand too, Python3 documentation vs
PyMOTW being available only for Python2.
As such, I am fine with the way things currently are. Stdlib
documentation is for reference and I search for PyMOTW to landup and
look for examples in Doug's documents and I use both of them in
tandem and needless to say, once a particular module becomes more
familiar, I tend to look for reference more than the example.
More information about the Python-ideas