You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomee.apache.org by Romain Manni-Bucau <rm...@gmail.com> on 2012/11/07 23:44:39 UTC
Fwd: Using comments.apache.org for our live docs
do we want it too?
*Romain Manni-Bucau*
*Twitter: @rmannibucau <https://twitter.com/rmannibucau>*
*Blog: **http://rmannibucau.wordpress.com/*<http://rmannibucau.wordpress.com/>
*LinkedIn: **http://fr.linkedin.com/in/rmannibucau*
*Github: https://github.com/rmannibucau*
---------- Forwarded message ----------
From: Rainer Jung <ra...@kippdata.de>
Date: 2012/11/7
Subject: Using comments.apache.org for our live docs
To: Tomcat Developers List <de...@tomcat.apache.org>, Tomcat Users List <
users@tomcat.apache.org>
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/<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<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<de...@tomcat.apache.org>
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: Using comments.apache.org for our live docs
Posted by Bharath Ganesh <bh...@gmail.com>.
+1 for sure!
Thanks,
Bharath
On Thu, Nov 8, 2012 at 11:56 AM, Vishwanath Krishnamurthi <
tovishwanath@gmail.com> wrote:
> Looks great ! We are slow on adding the changes to the docs and until a
> change is integrated to the doc, comments section
> could prove to be useful.
>
> -Vishwa
>
> On Thu, Nov 8, 2012 at 4:14 AM, Romain Manni-Bucau <rmannibucau@gmail.com
> >wrote:
>
> > do we want it too?
> >
> > *Romain Manni-Bucau*
> > *Twitter: @rmannibucau <https://twitter.com/rmannibucau>*
> > *Blog: **http://rmannibucau.wordpress.com/*<
> > http://rmannibucau.wordpress.com/>
> > *LinkedIn: **http://fr.linkedin.com/in/rmannibucau*
> > *Github: https://github.com/rmannibucau*
> >
> >
> >
> >
> > ---------- Forwarded message ----------
> > From: Rainer Jung <ra...@kippdata.de>
> > Date: 2012/11/7
> > Subject: Using comments.apache.org for our live docs
> > To: Tomcat Developers List <de...@tomcat.apache.org>, Tomcat Users List <
> > users@tomcat.apache.org>
> >
> >
> > 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/<
> > 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<
> > 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<de...@tomcat.apache.org>
> > For additional commands, e-mail: dev-help@tomcat.apache.org
> >
>
Re: Using comments.apache.org for our live docs
Posted by Jean-Louis MONTEIRO <je...@gmail.com>.
+1 with Vishwa
2012/11/8 Vishwanath Krishnamurthi <to...@gmail.com>
> Looks great ! We are slow on adding the changes to the docs and until a
> change is integrated to the doc, comments section
> could prove to be useful.
>
> -Vishwa
>
> On Thu, Nov 8, 2012 at 4:14 AM, Romain Manni-Bucau <rmannibucau@gmail.com
> >wrote:
>
> > do we want it too?
> >
> > *Romain Manni-Bucau*
> > *Twitter: @rmannibucau <https://twitter.com/rmannibucau>*
> > *Blog: **http://rmannibucau.wordpress.com/*<
> > http://rmannibucau.wordpress.com/>
> > *LinkedIn: **http://fr.linkedin.com/in/rmannibucau*
> > *Github: https://github.com/rmannibucau*
> >
> >
> >
> >
> > ---------- Forwarded message ----------
> > From: Rainer Jung <ra...@kippdata.de>
> > Date: 2012/11/7
> > Subject: Using comments.apache.org for our live docs
> > To: Tomcat Developers List <de...@tomcat.apache.org>, Tomcat Users List <
> > users@tomcat.apache.org>
> >
> >
> > 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/<
> > 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<
> > 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<de...@tomcat.apache.org>
> > For additional commands, e-mail: dev-help@tomcat.apache.org
> >
>
Re: Using comments.apache.org for our live docs
Posted by Vishwanath Krishnamurthi <to...@gmail.com>.
Looks great ! We are slow on adding the changes to the docs and until a
change is integrated to the doc, comments section
could prove to be useful.
-Vishwa
On Thu, Nov 8, 2012 at 4:14 AM, Romain Manni-Bucau <rm...@gmail.com>wrote:
> do we want it too?
>
> *Romain Manni-Bucau*
> *Twitter: @rmannibucau <https://twitter.com/rmannibucau>*
> *Blog: **http://rmannibucau.wordpress.com/*<
> http://rmannibucau.wordpress.com/>
> *LinkedIn: **http://fr.linkedin.com/in/rmannibucau*
> *Github: https://github.com/rmannibucau*
>
>
>
>
> ---------- Forwarded message ----------
> From: Rainer Jung <ra...@kippdata.de>
> Date: 2012/11/7
> Subject: Using comments.apache.org for our live docs
> To: Tomcat Developers List <de...@tomcat.apache.org>, Tomcat Users List <
> users@tomcat.apache.org>
>
>
> 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/<
> 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<
> 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<de...@tomcat.apache.org>
> For additional commands, e-mail: dev-help@tomcat.apache.org
>
Fwd: Using comments.apache.org for our live docs
Posted by Stephen Connolly <st...@gmail.com>.
Would be nice to integrate this into our Maven skin so that we could have
it too
---------- Forwarded message ----------
From: Romain Manni-Bucau <rm...@gmail.com>
Date: 7 November 2012 22:44
Subject: Fwd: Using comments.apache.org for our live docs
To: "dev@openejb.apache.org" <de...@openejb.apache.org>
do we want it too?
*Romain Manni-Bucau*
*Twitter: @rmannibucau <https://twitter.com/rmannibucau>*
*Blog: **http://rmannibucau.wordpress.com/*<
http://rmannibucau.wordpress.com/>
*LinkedIn: **http://fr.linkedin.com/in/rmannibucau*
*Github: https://github.com/rmannibucau*
---------- Forwarded message ----------
From: Rainer Jung <ra...@kippdata.de>
Date: 2012/11/7
Subject: Using comments.apache.org for our live docs
To: Tomcat Developers List <de...@tomcat.apache.org>, Tomcat Users List <
users@tomcat.apache.org>
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/<
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<
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<de...@tomcat.apache.org>
For additional commands, e-mail: dev-help@tomcat.apache.org