Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: Language features don't have rights. People do. :-) FWIW, there is precedent. We have type annotations in the language but don't use them throughout the docs. In the end, all that matters is usability. If a notion fails a usability test, then we should adapt accordingly. When it comes to documentation, we also try to minimize how much a person needs to know in order a mentally parse a piece in isolation. That is a core principle of documentation (the MS Excel docs are an excellent example; a counter-example is Wikipedia's use of the IPA pronunciation notation which is technically superior but is only readable/usable by very few of the readers.). P.S. I hope you don't come to personally identify with this patch. I'm a big admirer of your work and am already promoting the feature to my 50,000+ twitter follows. In this tracker issue, I hope for us a have a dispassionate, honest evaluation of what makes for the best documentation of the language. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37134> _______________________________________