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). Best regards, Konstantin Kolinko --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
