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 <rainer.j...@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-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
