The ASF has a Apache Comments System. It was started by a committer of the web server project in order to allow users to add comments to live docs web pages. It is currently by the web server and the trafficserver projects. The experience at the web server project is very positive. Most comments do make sense, there is only very little SPAM or other misuse and the typical volume is about 1-2 comments per day. The Tomcat community might be more active though.
Two weeks ago I started a discussion about including it into our public Tomcat docs as well. Some have expressed interest in the idea and there was some valuable feedback about improvements. Although docs are CTR the proposed change is not only about docs contents, but also about a new service offering to users. As such it will in the end put some more pressure on our precious time resources. This is why I start a formal vote thread. I propose to add the commenting feature to our live docs at tomcat.apache.org for version 7. Especially this means, that any user will be able to post any comment without moderation, except when including links. Any moderator can subscribe to all comments, mark comments or delete them or - if they contain links - release them. Any ASF committer is automatically a moderator for any site using comments.a.o. The implementation will be based on http://people.apache.org/~rjung/patches/tc-trunk-comments-v2.patch (some adjustments are obvious because it will be applied to TC 7 docs on tomcat.apache.org). A visual prototype is available at http://people.apache.org/~rjung/tomcat-docs-comments/tomcat-8.0-docs/ An explanation page that is linked from the comments system was drafted here: http://people.apache.org/~rjung/tomcat-docs-comments/tomcat-8.0-docs/comments.html Possible future enhancements: - Discuss whether we want new comments to be copied to the dev list - Discuss whether we want to invite some non-committers as moderators - Add to docs for version 6 and 5.5 with comments plugin informing users about comments existing on the same page in another version (relatively easy, soon) - Add to connectors and native docs (needs investigation) - Add to other site pages and migration guide (not sure) - Improve styles, probably making the comments threads more consistent with the docs There is currently no good way to share comments between different sites that serve the same docs, like our CI system and the main tomcat site. IMHO it is already valuable to allow comments on the main site. Integrate comments.apache.org with TC 7 docs on tomcat.apache.org: [ ] +1, go ahead [ ] 0, I don't care [ ] -1, Don't integrate, because ... Regards, Rainer --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
