Guido, was it your intention that this show-up everywhere in the docs.  I had thought the primary motivation was to make it possible to write pure python code that exactly matched a C API.   

ISTM, there is no need to confront every single user of the docs with a notation that is known to be confusing.  From a teacher's point of view, pushing this notation everywhere in the docs changes the priority of the topic.  Formerly, it was an optional intermediate/advanced topic.  But if it is visible everywhere, it becomes an unavoidable day one topic for every single learner (that is if we want them to be able to read and understand the docs).