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

Nick Coghlan ncoghlan at gmail.com
Sat Mar 19 23:29:22 CET 2011


On Sun, Mar 20, 2011 at 8:19 AM, Alexander Belopolsky
<alexander.belopolsky at gmail.com> wrote:
> I am sure there are instances when a PyMOTW is a valuable addition to
> the "official" module documentation, but I think a decision to link it
> should be made on a case by case basis by someone who would review
> both the official and PyMOTW pages and decide that a link to PyMOTW
> adds to the quality of documentation for a given module.

I think this is another case where "perfect is the enemy of good", though.

Perfect: a broader "Python Documentation Index" that collects and
curates links to documentation of various Python topics, including the
standard library modules
Perfect: a case-by-case comparison of the stdlib docs and the PyMOTW
docs for each module by a module expert, deciding whether or not to
link to the PyMOTW version in a "See Also" link

Good: just link them all as part of the module documentation
generation process. Some people may understand the stdlib docs better,
some may understand PyMOTW better, but providing ready access to both
is unlikely to actively *confuse* anyone that wasn't already lost.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia



More information about the Python-ideas mailing list