[Python-ideas] PEP links in docs

[spir]

Le Mon, 16 Mar 2009 16:54:44 -0700,
Aahz <aahz at pythoncraft.com> s'exprima ainsi:

> On Mon, Mar 16, 2009, Raymond Hettinger wrote:
> >attribution for Georg Brandl deleted:
> >>
> >> Feel free to send patches, as small as they may seem.  Mark up PEP
> >> numbers in reST like this -- :pep:`42` -- to get automatic linking.
> >
> > We might want to include a PEP index in the documentation
> > but I think it's a really bad idea to include links from within
> > the docs.  The PEPs get out of date quickly.  They document
> > an early decision but not its ultimate evolution and diffusion
> > through-out the language.
> 
> There are two reasons to link to PEPs:
> 
> * Provide the historical context

Agree with Raymond. It should be made clear along with the pointer that the pointed PEP could be outdated. Maybe simply writing
	(original PEP: :pep:`42`)
is enough? The word 'original' implicitely stating that things could have changed?

> * Give detailed info lacking in the docs
> 
> The first purpose will always exist, and I see no reason to delete such
> a link if documented as such.  Links for the latter purpose can be
> removed when the docs are updated to match what's available in the PEP.

To me the most important aspect is not about having details (still, it's important). Instead it is to get an (even partial or obscure) answer to "why", that often simply misses in the official docs. This answer is necessary to interpret the "what" and/or "how". Nobody can properly understand a feature description without knowing its purpose. In the best case, the reader will guess it, in he worst, he will guess wrong. Explicit is better than... also for docs!

There is also a pedagogical aspect that I find even more relevant. An unexperienced programmer or pythonist should at least be able to figure out vaguely what this or that feature is about. No doubt this is very difficult to achieve -- especially for experts! I imagine a 2-stage "why" introduction to every feature description in the docs: the first one targeted to non-specialists, the second one more technical. (I'm sure that the first one would also sometimes help specialists.)
The pedagogical one must be worded by, or reviewed by, or written in colloboration with, "tutors" that are able to imagine where/how/why newbies may stuck. It needs not beeing long -- sometimes a few words may be enough. (But it will sometimes be the hardest part ;-). It would also benefit from newbie feedback. I wonder whether this task could be partially delegated to the python-tutor mailing list activists.

Denis

PS: If ever, I volonteer to take part to this kind of task -- for the french version. [Have been technical trainer (in automation) in a previous life.]

------
la vita e estrany