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