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

[Ned Batchelder]

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.

A link to the PEP is appropriate as a "see also" in the docs, but we 
shouldn't pretend that a PEP addresses the needs of people new to the 
feature.

--Ned.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20131011/e005bde0/attachment.html>