You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by Rainer Jung <ra...@kippdata.de> on 2012/11/07 23:31:06 UTC
Using comments.apache.org for our live docs
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
Re: Using comments.apache.org for our live docs
Posted by Pid <pi...@pidster.com>.
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]
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 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 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
Fwd: Using comments.apache.org for our live docs
Posted by Romain Manni-Bucau <rm...@gmail.com>.
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 Tim Funk <fu...@apache.org>.
Nice. +1
-Tim
On Wed, Nov 7, 2012 at 5:31 PM, Rainer Jung <ra...@kippdata.de> wrote:
<SNIP>
> 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>
>
>
Re: Using comments.apache.org for our live docs
Posted by Rainer Jung <ra...@kippdata.de>.
Thanks Konstantin. Will work over the weekend on your valuable remarks.
On 08.11.2012 23:25, Konstantin Kolinko wrote:
> 2012/11/8 Rainer Jung <ra...@kippdata.de>:
>> 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.
>>
>
> Nice.
>
> Several notes:
>
>> A final version would include a reference to tomcat.apache.org
>
> 1. I think it needs to also allow tomcat.[eu|us].apache.org mirrors
> and ci.apache.org where nightly builds of documentation are published.
>
> 2. I think that the comments should be be hidden when the document is
> being printed.
>
> 3. Regarding the "Comments" section header and notice
>
> I think it would be better
> a) to have this section more distinct from the rest of the page
> (formatted as something "external" to the page itself), and
>
> b) to write proper introduction to the comments feature somewhere one
> (formatted as a proper chapter/section of the documentation),
> e,g, in the "Introduction" chapter, or maybe on the main tomcat.apache.org site.
>
> The short notice section can have a link to this introduction.
>
>
> Regarding the notice section, or rather the introduction to the
> feature if we write one,
> I would like to see the following:
> 1) Maybe do not mention the IRC channel.
> 2) Maybe mention how the comments are used. (Copyrights, AL)
> 3) Maybe mention who sees the comments (Those who subscribe to receive
> them. They are not forwarded to the public mailing list).
>
> Looking at httpd.a.o,
> - the comments section header there spans the whole page width.
> - the "Available Languages" line is above it.
> - the "notice" is distinct from the rest of text by using a red border
> - documentation and comments style is more consistent. They use the same font
>
>
> 4. Looking at httpd.a.o, I noticed a nice feature:
> http://httpd.apache.org/docs/2.2/configuring.html
> http://httpd.apache.org/docs/2.4/configuring.html
>
> The "2.2" page has comments, the "2.4" does not. The following footer
> is added to the "2.4" page:
> "The 2.2 branch of the documentation has comments available for this
> page. Click here to view them."
>
>
> 5. It does not work well when I browse the main site through https.
>
> It works, but most of the links back and forth redirect to the http
> version of it.
> Examples:
> a) The " Click here to view them." link mentioned above
> b) The "View" link on a comment in the list of comments on comments.apache.org
>
>
> 6. It is not clear what is lifecycle of a comment.
>
> I see that when I log in then there is a link above each comment that
> allows to mark it as "Resolved". When (and who) is removing resolved
> comments?
> E.g. someone is supposed to do a manual sweep once the next minor
> Tomcat version is released and its updated documentation is published?
> The dashboard GUI is not very friendly for such a task.
>
> Some message boards have a feature where a comment can be marked to
> auto-disappear after certain time (e.g. several days).
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: Using comments.apache.org for our live docs
Posted by Rainer Jung <ra...@kippdata.de>.
On 22.11.2012 12:43, Konstantin Kolinko wrote:
> 2012/11/20 Rainer Jung <ra...@kippdata.de>:
>> On 08.11.2012 23:25, Konstantin Kolinko wrote:
>>> 2012/11/8 Rainer Jung <ra...@kippdata.de>:
>> So I suggest to support comments only on the official tomcat.a.o and use
>> full page URLs as the prototype does.
>>
>
> If we need a single official URL, I would prefer to use
> https://tomcat.apache.org/ (with HTTPS). As in "better be safe".
>
> Other than that I am OK with enabling the feature on tomcat.a.o only.
I think for http and https there might be some code in comments. I'll
check whether we can support http and https in parallel.
>> Updated patch available at
>> http://people.apache.org/~rjung/patches/tc-trunk-comments-v2.patch
>
> +1. Good.
>
> There is stray "+LICENSE" line before "<section name="Privacy
> Policy">" in comments.xml.
Right, I added the word as a reminder when I wrote the file and forgot
to remove it.
> I think you'll want to apply additional
> menu items (those additions in project.xml files) regardless of this
> patch.
Mr Eagle eye :)
Regards,
Rainer
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: Using comments.apache.org for our live docs
Posted by Konstantin Kolinko <kn...@gmail.com>.
2012/11/20 Rainer Jung <ra...@kippdata.de>:
> On 08.11.2012 23:25, Konstantin Kolinko wrote:
>> 2012/11/8 Rainer Jung <ra...@kippdata.de>:
>
>> Several notes:
>>
>>> A final version would include a reference to tomcat.apache.org
>
> Yes, noted.
>
>> 1. I think it needs to also allow tomcat.[eu|us].apache.org mirrors
>> and ci.apache.org where nightly builds of documentation are published.
>
> It would be trivial to include those hosts in the server name check.
> But: any comment is associated with a URL. Either you send an explicit
> URL, when the comment is added, or the comments server uses the URL in
> the Referer header. Now that URL serves two purposes:
>
> - the comment add command returns with a redirect to that page. So the
> URL should be self-referential, otherwise adding a comment would kick
> you off the previous page.
>
> - the URL is linked from the comments dashboard
>
> If we wanted multiple sites who serve our docs to share the comments,
> then the page URL we sent needs to be an URI without server and port.
> Still all the sites would need to have a uniform URI structure. At least
> ci will not have the same URI structure for the docs as tomcat.a.o.
> tomcat.eu and tomcat.us will. The downside to switching to a URI is,
> that the links form the dashboard will be broken.
>
> So I suggest to support comments only on the official tomcat.a.o and use
> full page URLs as the prototype does.
>
If we need a single official URL, I would prefer to use
https://tomcat.apache.org/ (with HTTPS). As in "better be safe".
Other than that I am OK with enabling the feature on tomcat.a.o only.
> Updated patch available at
> http://people.apache.org/~rjung/patches/tc-trunk-comments-v2.patch
+1. Good.
There is stray "+LICENSE" line before "<section name="Privacy
Policy">" in comments.xml. I think you'll want to apply additional
menu items (those additions in project.xml files) regardless of this
patch.
Best regards,
Konstantin Kolinko
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: Using comments.apache.org for our live docs
Posted by Rainer Jung <ra...@kippdata.de>.
Hi Konstantin,
as always thanks for your thorough review. Comments inline.
On 08.11.2012 23:25, Konstantin Kolinko wrote:
> 2012/11/8 Rainer Jung <ra...@kippdata.de>:
> Several notes:
>
>> A final version would include a reference to tomcat.apache.org
Yes, noted.
> 1. I think it needs to also allow tomcat.[eu|us].apache.org mirrors
> and ci.apache.org where nightly builds of documentation are published.
It would be trivial to include those hosts in the server name check.
But: any comment is associated with a URL. Either you send an explicit
URL, when the comment is added, or the comments server uses the URL in
the Referer header. Now that URL serves two purposes:
- the comment add command returns with a redirect to that page. So the
URL should be self-referential, otherwise adding a comment would kick
you off the previous page.
- the URL is linked from the comments dashboard
If we wanted multiple sites who serve our docs to share the comments,
then the page URL we sent needs to be an URI without server and port.
Still all the sites would need to have a uniform URI structure. At least
ci will not have the same URI structure for the docs as tomcat.a.o.
tomcat.eu and tomcat.us will. The downside to switching to a URI is,
that the links form the dashboard will be broken.
So I suggest to support comments only on the official tomcat.a.o and use
full page URLs as the prototype does.
> 2. I think that the comments should be be hidden when the document is
> being printed.
Done using the noPrint style as already used in other parts.
> 3. Regarding the "Comments" section header and notice
>
> I think it would be better
> a) to have this section more distinct from the rest of the page
> (formatted as something "external" to the page itself), and
I'm open to any visual improvements. Unfortunately this is not one of my
strengths. I tried to keep it consistent with the rest of TC docs.
But see below for the "Notice" formatting.
> b) to write proper introduction to the comments feature somewhere one
> (formatted as a proper chapter/section of the documentation),
> e,g, in the "Introduction" chapter, or maybe on the main tomcat.apache.org site.
I added one to the top-level of the documentation, since it would be
neither part of the users guide alone, nor of the config reference. It
is referenced from each comments notice. The comments sections of the
pages are now also linked under the "Links" menu of each page.
Some more info about the comments system is available at:
https://comments.apache.org/help.html
> The short notice section can have a link to this introduction.
Done.
> Regarding the notice section, or rather the introduction to the
> feature if we write one,
> I would like to see the following:
> 1) Maybe do not mention the IRC channel.
Removed.
> 2) Maybe mention how the comments are used. (Copyrights, AL)
Added the the comments.html page
> 3) Maybe mention who sees the comments (Those who subscribe to receive
> them. They are not forwarded to the public mailing list).
Subscription mentioned for moderators.
> Looking at httpd.a.o,
> - the comments section header there spans the whole page width.
> - the "Available Languages" line is above it.
For httpd.a.o it is consistent with the rest of the docs, I tried to
make ours consistent with our docs. As said, if someone can do better,
we can adjust.
> - the "notice" is distinct from the rest of text by using a red border
Done.
> - documentation and comments style is more consistent. They use the same font
The system allows three pre-defined styles and also providing our own
style for the comments. See
https://comments.apache.org/help.html#styling
I would prefer someone else doing the look and feel. I'd say this is not
a show-stopper (the default styles for the comments threads don't look bad).
> 4. Looking at httpd.a.o, I noticed a nice feature:
> http://httpd.apache.org/docs/2.2/configuring.html
> http://httpd.apache.org/docs/2.4/configuring.html
>
> The "2.2" page has comments, the "2.4" does not. The following footer
> is added to the "2.4" page:
> "The 2.2 branch of the documentation has comments available for this
> page. Click here to view them."
I checked the sources of the comments system. There is a special plugin
for httpd, a small lua script, that knows how to derive the product
version from a docs URL and has some very basic rules, which version
checks which other version in case no comments are present. It will be
easy to copy and adjust this for Tomcat, once the comments are in place.
https://svn.apache.org/repos/infra/infrastructure/trunk/projects/comments/scripts/show_comments_httpd.lua
It might get a bit more complex, if we want more subtle logic, like
listing all other versions that have comments.
IMHO not a show stopper.
> 5. It does not work well when I browse the main site through https.
>
> It works, but most of the links back and forth redirect to the http
> version of it.
> Examples:
> a) The " Click here to view them." link mentioned above
> b) The "View" link on a comment in the list of comments on comments.apache.org
Do you have any other examples, that occur if a normal user works with
comments (no dashboard, no version plugin)?
> 6. It is not clear what is lifecycle of a comment.
>
> I see that when I log in then there is a link above each comment that
> allows to mark it as "Resolved". When (and who) is removing resolved
> comments?
The actions "Resolved", "Invalid" and "Sticky" only show up for logged
in moderators. You can choose one of them to mark the comment. The
latest one chosen will overwrite previous ones. The mark can be removed
with "Unflag". So those only change a visual status of the comment.
Only "Delete" will remove the comment. This is also a moderator action.
All ASF committers are allowed to moderate comments on any site. We can
also give moderation permission to interested users (per site), who e.g.
regularly help on the users list.
> E.g. someone is supposed to do a manual sweep once the next minor
> Tomcat version is released and its updated documentation is published?
> The dashboard GUI is not very friendly for such a task.
The goal here is not being perfect but allowing user feedback.
If one of us includes a comment in the docs, he can set the "Resolved"
flag immediately without waiting for the next version.
I agree, that adding e.g. the active flags and the creation time of a
comment to the dashboard and being able to sort by them would be
helpful. I found Daniel (humbedooh@apache.org) who created the system
extremely helpful and responsive, so I'm confident we will see improvements.
> Some message boards have a feature where a comment can be marked to
> auto-disappear after certain time (e.g. several days).
Another interesting suggestion. Or depending on our experience, probably
a way of listing and deleting stuff that's older then some chosen threshold.
Updated patch available at
http://people.apache.org/~rjung/patches/tc-trunk-comments-v2.patch
Regards,
Rainer
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: Using comments.apache.org for our live docs
Posted by Konstantin Kolinko <kn...@gmail.com>.
2012/11/8 Rainer Jung <ra...@kippdata.de>:
> 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.
>
Nice.
Several notes:
> A final version would include a reference to tomcat.apache.org
1. I think it needs to also allow tomcat.[eu|us].apache.org mirrors
and ci.apache.org where nightly builds of documentation are published.
2. I think that the comments should be be hidden when the document is
being printed.
3. Regarding the "Comments" section header and notice
I think it would be better
a) to have this section more distinct from the rest of the page
(formatted as something "external" to the page itself), and
b) to write proper introduction to the comments feature somewhere one
(formatted as a proper chapter/section of the documentation),
e,g, in the "Introduction" chapter, or maybe on the main tomcat.apache.org site.
The short notice section can have a link to this introduction.
Regarding the notice section, or rather the introduction to the
feature if we write one,
I would like to see the following:
1) Maybe do not mention the IRC channel.
2) Maybe mention how the comments are used. (Copyrights, AL)
3) Maybe mention who sees the comments (Those who subscribe to receive
them. They are not forwarded to the public mailing list).
Looking at httpd.a.o,
- the comments section header there spans the whole page width.
- the "Available Languages" line is above it.
- the "notice" is distinct from the rest of text by using a red border
- documentation and comments style is more consistent. They use the same font
4. Looking at httpd.a.o, I noticed a nice feature:
http://httpd.apache.org/docs/2.2/configuring.html
http://httpd.apache.org/docs/2.4/configuring.html
The "2.2" page has comments, the "2.4" does not. The following footer
is added to the "2.4" page:
"The 2.2 branch of the documentation has comments available for this
page. Click here to view them."
5. It does not work well when I browse the main site through https.
It works, but most of the links back and forth redirect to the http
version of it.
Examples:
a) The " Click here to view them." link mentioned above
b) The "View" link on a comment in the list of comments on comments.apache.org
6. It is not clear what is lifecycle of a comment.
I see that when I log in then there is a link above each comment that
allows to mark it as "Resolved". When (and who) is removing resolved
comments?
E.g. someone is supposed to do a manual sweep once the next minor
Tomcat version is released and its updated documentation is published?
The dashboard GUI is not very friendly for such a task.
Some message boards have a feature where a comment can be marked to
auto-disappear after certain time (e.g. several days).
Best regards,
Konstantin Kolinko
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org