Message344652
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. |
|
Date |
User |
Action |
Args |
2019-06-04 21:57:29 | rhettinger | set | recipients:
+ rhettinger, tim.peters, barry, brett.cannon, gregory.p.smith, ncoghlan, vstinner, docs@python, willingc, bskinn, p-ganssle, pablogsal, grantjenks |
2019-06-04 21:57:29 | rhettinger | set | messageid: <1559685449.2.0.451931870406.issue37134@roundup.psfhosted.org> |
2019-06-04 21:57:29 | rhettinger | link | issue37134 messages |
2019-06-04 21:57:29 | rhettinger | create | |
|