Mailing-List: contact dev-help@tomcat.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Tomcat Developers List" <dev@tomcat.apache.org>
Received-SPF: pass (athena.apache.org: domain of rainer.jung@kippdata.de
 designates 195.227.30.149 as permitted sender)
Message-ID: <509AE12A.6040509@kippdata.de>
Date: Wed, 07 Nov 2012 23:31:06 +0100
From: Rainer Jung <rainer.jung@kippdata.de>
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64;
 rv:16.0) Gecko/20121026 Thunderbird/16.0.2
MIME-Version: 1.0
To: Tomcat Developers List <dev@tomcat.apache.org>,
        Tomcat Users List <users@tomcat.apache.org>
Subject: Using comments.apache.org for our live docs
Content-Type: text/plain; charset=ISO-8859-15; format=flowed
Content-Transfer-Encoding: 7bit

Cross posting intentionally, because our long time users list supporters 
might want to comment as well.

A few months ago a new Web Server committer, Daniel Gruno, suggested to 
use a commenting system as part of the online documentation. He wanted 
to include the disqus system. Some of his fellow committers were not 
very glad with using an external system for the users comments and he 
sat down and wrote an ASF commenting system. It is now running as an ASF 
service under comments.apache.org.

It allows users to add comments to documentation pages. Comments without 
URLs and HTML tags are going live immediately without moderation, the 
other ones need moderation first.

We are using it in the web server project since a few months and we 
observe close to no spam. Comment activity isn't to high, about 1 
comments per day. Some of those are not actually docs comments and they 
are responded by referring the users to the users list. Some of them are 
really useful because they help to clarify and improve documentation. In 
the meantime, the trafficserver project also uses the feature.

The comments are not meant to stay forever. Important content should be 
integrated into the docs.

Technically the commenting is done by adding a few lines of html and 
inline JavaScript to each page, which then calls comments.apache.org. 
For the Tomcat docs this can be done by adding those items to the XSL 
stylesheet used to generate the HTML pages.

I prepared a simple demo at:

http://people.apache.org/~rjung/tomcat-docs-comments/tomcat-8.0-docs/

It would be nice if you would have a look and we would discuss, whether 
we find it useful or not. The patch for build.xml and the xsl that I 
applied to build the comment enabled docs can be found at

http://people.apache.org/~rjung/patches/tc-trunk-comments.patch

A final version would include a reference to tomcat.apache.org instead 
of people.apache.org/... The JavaScript checks the host header in order 
to disable the feature if the docs are running on a different server, 
e.g. inside a localhost Tomcat etc.

Regards,

Rainer

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org