tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Pid <...@pidster.com>
Subject Re: Using comments.apache.org for our live docs
Date Thu, 08 Nov 2012 20:49:20 GMT
On 07/11/2012 22:31, Rainer Jung wrote:
> 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/

I like it.  :)


p


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


-- 

[key:62590808]


Mime
View raw message