[Python-Dev] PEPs shouldn't be considered docs

[Benjamin Peterson]

2013/10/11 Ned Batchelder <ned at nedbatchelder.com>:
> I wanted to teach a co-worker about "from __future__ import absolute_import"
> today, so I thought I'd point them at the docs.  The page for "__future__"
> starts with a bunch of internal details that almost no one needs to know.
> There's a table at the end that mentions the actual importable names,
> including "absolute_import", but says nothing about then except to link to a
> PEP.
>
> The absolute imports PEP has no simple description of what it does. Like
> many PEPs, it's mostly a summary of the debate around the design of the
> feature. The closest the PEP comes to describing the behavior of
> "absolute_import" is this parenthetical:
>
> For the second problem, it is proposed that all import statements be
> absolute by default (searching sys.path only) with special syntax (leading
> dots) for accessing package-relative imports.
>
> And notice: that sentence describes it as a "proposal."
>
> I'd like to suggest that we not consider PEPs to be documentation.  If a PEP
> has a good succinct description of how something works, then let's copy that
> text into the documentation at an appropriate place.  If a PEP doesn't have
> such a description, then all the more reason not to send readers there.

+1 The writing required to specificy and adovocate a feature are
usually quite different from that needed to document it. PEPs also get
out of date rather quickly.



-- 
Regards,
Benjamin