[GitHub] tomcat issue #79: remove placeholders from introduction doc
Github user ChristopherSchultz commented on the issue: https://github.com/apache/tomcat/pull/79 References: https://apacheconna2015.sched.com/event/2P6d/rtfm-write-a-better-fm-rich-bowen-apache-software-foundation http://feathercast.apache.org/podcasts/ApacheConNA2015/Monday/Community/Monday_Community_04%20-%20Rich%20Bowen%20-%20RTFM%20-%20Write%20a%20Better%20FM.mp3 http://drbacchus.com/rtfm-write-a-better-fm-recording/ --- - To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
[GitHub] tomcat issue #79: remove placeholders from introduction doc
Github user ChristopherSchultz commented on the issue: https://github.com/apache/tomcat/pull/79 A few years ago, Rich Bowen gave a talk @ ApacheCon about documentation and communities. He used Python as an example of a community where the Monty Python jokes are so pervasive, it appears that they have become the focus of the documentation instead of the actual subject (the code, etc.). He suggested that humor, while intended to be fun, lighthearted, etc. often comes across as mean-spirited or condescending, and/or introduces confusion especially to those who do not understand (a) the language (e.g. English), (b) that they are in fact jokes or (c) the content of the jokes (e.g. unfamiliar with Monty Python). Basically, this kind of thing doesn't have a place in high-quality documentation. This example is relatively benign, but there are probably other places where the humor is at least distracting if not worse. --- - To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
[GitHub] tomcat issue #79: remove placeholders from introduction doc
Github user pmcelhaney commented on the issue: https://github.com/apache/tomcat/pull/79 IMHO the humor doesnât work here. It comes across as condescending. Itâs *definitely* not helpful. --- - To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
[GitHub] tomcat issue #79: remove placeholders from introduction doc
Github user markt-asf commented on the issue: https://github.com/apache/tomcat/pull/79 We could pull the entries and add "That's it!" after the list. --- - To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
[GitHub] tomcat issue #79: remove placeholders from introduction doc
Github user csutherl commented on the issue: https://github.com/apache/tomcat/pull/79 This is a least the fourth time I've seen someone asking about this. Should we make a note or use a sarcasm font or something? :) It's funny, but seems to be confusing new folks. --- - To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
[GitHub] tomcat issue #79: remove placeholders from introduction doc
Github user markt-asf commented on the issue: https://github.com/apache/tomcat/pull/79 Those aren't placeholders. It is intentional content. I believe they are meant to be a lighthearted way of indicating that 'Context' is the only term that needs introducing. --- - To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
