> 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.