[issue21956] Doc files deleted from repo are not deleted from docs.python.org.

[Brandon Rhodes]

Brandon Rhodes added the comment:

Now that I am back at a full keyboard, I see that my previous response
to @BreamoreBoy about this issue is too short and too cryptic to really
serve as a fair answer to his question.  And, with some embarrassment, I
note that my words did not even achieve the dignity of forming an actual
English sentence.  Alas for cramped travel laptop keyboards and airport
wi-fi!

Might I be allowed another try?  If so, then: @BreamoreBoy, I think that
your confusion ("How does that translate?") can be blamed squarely on
the document in question.  Instead of introducing and maintaining a
consistent terminology, it manages to burden the reader with two
parallel and redundant sets of terms for exactly the same idea.

In short, the document title does not match the document itself.

The title of the document sets forth the terms "Idiom" and "Anti-idiom"
as its subject.  But then it completely drops the ball.  The terms are
not defined in the document itself.  They are not clarified anywhere in
its text.  Nor are they even *used* anywhere in its body, with a single
lonely exception buried down somewhere around the middle (second
paragraph under "Exceptions").

Instead, the body uses the simpler phrases "Do", "do not", and "should
not."  It is running in its "do not" / "don't" mode when it reaches the
sentence you quote, Mark, about "from...import" statements.

So the answer to your "How does that translate" question is that what
the title promises as "Idioms" and "Anti-idioms" actually come out
verbally in the text as "do" and "don't" instead.  When someone jumps
into the middle of the document without context, they see only "do" or
"don't" and are left wondering where the terminology of "idioms" is even
coming from.  But it comes directly from the title, as the only possible
mapping between the document's terms and those of its title.

So when the document says:

    from module import name1, name2. - This is a "don’t"...

the careful reader who has noticed and remembered the title will
simultaneously read:

    from module import name1, name2. - This is an anti-idiom...

Which is almost exactly the text of Audrey's tweet.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue21956>
_______________________________________