tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rainer Jung <rainer.j...@kippdata.de>
Subject Re: Using comments.apache.org for our live docs
Date Sat, 17 Nov 2012 12:55:31 GMT
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.jung@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


Mime
View raw message