[Python-ideas] PEP links in docs

[spir]

Le Mon, 16 Mar 2009 10:25:00 -0700,
Zac Burns <zac256 at gmail.com> s'exprima ainsi:

> I would like to see links to relevant PEP / mailing list docs in the main
> docs.

+++

PEPs -- with purpose and rationale, and deeply reviewed -- are most often great. There are actually often more legible even for non-specialists, simply because they tell you why.
If one doesn't understand the PEP's introduction, then yes, probably this person does not need the feature ;-)

> For example http://docs.python.org/library/dircache.html after
> "Deprecated since version 2.6" could include a (PEP x.x) link where I
> could read why it was deprecated and probably what to use in it's
> place.
> 
> The docs right now are quite excellent describing the "what" about
> everything, but often have little to say about the "why". This is a
> good thing, but links would surely help those that want to learn more.

More than true, imo.
Every feature documentation could (should?) start answering the infamous "why?"; meaning the purpose, issue,... I really do not agree with the "if you don't know why, you don't need it" (elitist) argument.

Denis
------
la vita e estrany