You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by pmcelhaney <gi...@git.apache.org> on 2017/10/19 16:08:23 UTC
[GitHub] tomcat pull request #79: remove placeholders from introduction doc
GitHub user pmcelhaney opened a pull request:
https://github.com/apache/tomcat/pull/79
remove placeholders from introduction doc
You can merge this pull request into a Git repository by running:
$ git pull https://github.com/pmcelhaney/tomcat patch-1
Alternatively you can review and apply these changes as the patch at:
https://github.com/apache/tomcat/pull/79.patch
To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:
This closes #79
----
commit 0a4834f548b5880b4c6ffae08fcb741b74a405b2
Author: Patrick McElhaney <pa...@fisglobal.com>
Date: 2017-10-19T16:07:42Z
remove placeholders from introduction doc
----
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
[GitHub] tomcat issue #79: remove placeholders from introduction doc
Posted by markt-asf <gi...@git.apache.org>.
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-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
[GitHub] tomcat issue #79: remove placeholders from introduction doc
Posted by ChristopherSchultz <gi...@git.apache.org>.
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-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
[GitHub] tomcat issue #79: remove placeholders from introduction doc
Posted by ChristopherSchultz <gi...@git.apache.org>.
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-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
[GitHub] tomcat issue #79: remove placeholders from introduction doc
Posted by markt-asf <gi...@git.apache.org>.
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-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
[GitHub] tomcat pull request #79: remove placeholders from introduction doc
Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:
https://github.com/apache/tomcat/pull/79
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
[GitHub] tomcat issue #79: remove placeholders from introduction doc
Posted by csutherl <gi...@git.apache.org>.
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-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
[GitHub] tomcat issue #79: remove placeholders from introduction doc
Posted by pmcelhaney <gi...@git.apache.org>.
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-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org