Pablo Galindo Salgado <pablogsal@gmail.com> added the comment:
FWIW, there is precedent. We have type annotations in the language but don't use them throughout the docs.
Although there is some distance between both cases, I think this is an extremely good point to take into account that I have not thought about.
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.
Not at all :). I will be happy whatever solution we end agreeing to, knowing that we are going through a very thorough discussion. But thank you very much for stopping the discussion to check. I actually apologize if any of my responses have been more passionate than it should have been. I (really!) appreciate your words here and the fact that even if you disagree with this change and the cost of the feature regarding the advantages, you are making a lot of effort to explain the feature to users. Thank you very much for caring about the language, users and having a healthy and productive discussion. ---------- keywords: +easy title: Use PEP570 syntax in the documentation -> [EASY] Use PEP570 syntax in the documentation _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue37134> _______________________________________