Mailing List Archive

[Httpd Wiki] Update of "DocsCommentSystem" by DanielGruno
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Httpd Wiki" for change notification.

The "DocsCommentSystem" page has been changed by DanielGruno:
http://wiki.apache.org/httpd/DocsCommentSystem

New page:
= Documentation commentary system =
This document describes the proposed changes to the Apache HTTP Server documentation, in which a commentary system will be added, thus enabling people to comment on (almost) every page in the documentation.

== Proposed solution ==
The currently proposed solution is to use the Disqus comment system ( http://www.disqus.com ), as it is a mature system with plenty of moderation options, and it would allow us to make use of commentary without having to develop a new system in-house.

=== Technology ===
The comments are added using a JavaScript snippet at the bottom of each page. Furthermore, a new section, called "Comments" will be added to the bottom of each affected page. This section is already ready for most translations, as it uses the build system's locale feature for setting the title of the section. As this will be incorporated directly into the XSL documents, there will be no need for documenters to add anything new to any page, it will happen automatically with each affected page.

=== Which pages can be commented ===
The comment system will be available for all how-to guides and module pages. All index pages, quick references and the likes will not have the comment system attached to them. Furthermore, the comment system will not be available in the CHM or zipped versions (WAR?) of the documentation.

=== Languages ===
We have the option of eiher run a separate comment thread for each translation of each document, or run it as a unified commentary, i.e. we can run a separate comment thread for the English and the French version of mod_lua.html or we can have them both display the same comments - this has yet to be decided.

=== Moderating comments ===
Comments will be moderated by appointed moderators. Currently, for our test run, we have Rich Bowen, Igor Galic and Daniel Gruno as moderators, but more can be added. The moderator control panel is available through http://httpd.disqus.com Upon the arrival of new comments, these moderators will be notified via email that a new comment has been added, and can review it and select appropriate actions towards it.

Comments that have links in them, or comments that have an image attached WILL NOT be shown unless they have been approved by a moderator. This feature can be extended to include all comments, and we also have the option of requiring that people have registered with Disqus before they can comment.

=== Comments in offline documents ===
For security reasons, user friendliness and other browser quirkiness issues, the comments will not be available for viewing when viewing the documentation from any other place than httpd.a.o.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Httpd Wiki] Update of "DocsCommentSystem" by DanielGruno [ In reply to ]
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Httpd Wiki" for change notification.

The "DocsCommentSystem" page has been changed by DanielGruno:
http://wiki.apache.org/httpd/DocsCommentSystem?action=diff&rev1=1&rev2=2

= Documentation commentary system =
This document describes the proposed changes to the Apache HTTP Server documentation, in which a commentary system will be added, thus enabling people to comment on (almost) every page in the documentation.
+
+ == Why? ==
+ The reasons for wanting to add comments to the system are plenty:
+
+ * As a means to offer feedback on the document
+ * As a means to offer examples, bug reports, and grammatical fixes.
+ * As a means to tell us what's missing from the document, or ask questions, or what not.
+ * As a possible means of recruiting new committers and general contributors by lowering the bar for contributing to the documentation effort

== Proposed solution ==
The currently proposed solution is to use the Disqus comment system ( http://www.disqus.com ), as it is a mature system with plenty of moderation options, and it would allow us to make use of commentary without having to develop a new system in-house.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Httpd Wiki] Update of "DocsCommentSystem" by DanielGruno [ In reply to ]
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Httpd Wiki" for change notification.

The "DocsCommentSystem" page has been changed by DanielGruno:
http://wiki.apache.org/httpd/DocsCommentSystem?action=diff&rev1=4&rev2=5

Comment:
Added some discussion topics at the bottom of the page

=== Comment Exports ===
Discus supports an XML export of comments. We need to decide whether we want to do exports and if so, where to store the data. Primary reason for regular exports could be to save the content in case that the discus service is stopped.

+ == Questions for further discussion ==
+ * Should translations have their own separate discussion threads, or should they show the same thread as the English version?
+ * If this is adopted to other branches, should 2.4 and trunk (and possibly 2.2) be linked, or should each branch have a separate discussion per subject?
+ * Should we do regular XML exports of the discussion, and if so, where should we store it?
+ * Who will moderate, and how will new moderators be picked?
+ * Which approach to moderating the discussions would be best? For instance, should we approve all comments before they are shown, and who should be allowed to comment?
+

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [Httpd Wiki] Update of "DocsCommentSystem" by DanielGruno [ In reply to ]
On 05/23/2012 09:26 AM, Lucien Gentis wrote:
> Hello everybody,
>
> Le 23 mai 2012 à 06:28, Apache Wiki a écrit :
>
>>
>> == Questions for further discussion ==
>> * Should translations have their own separate discussion threads,
>> or should they show the same thread as the English version?
>
> A few days ago, httpd comment system was compared to PHP docs comment
> system.
>
> Just a few remarks :
>
> --- all PHP docs comments are in english and are the same in all
> translated pages : I should have rather seen french comments in french
> pages, turkish comments in turkish pages . . . , but on the other
> hand, if there is only one thread (in english) for each comment, it
> could be seen in all translated pages by all readers, which, I think,
> would be better for content related comments, but not for comments
> about a translation problem, for example.
> Could it be possible for a 'commenter' to make a choice between adding
> his/her comment only for the considered page, or for all languages pages ?
Everything is possible on the Interweb, but I think this might be a tad
complex.
As Rich pointed out, we will most likely be deleting comments if they
are implemented, invalid or off-topic, so I don't think that having
people remark on translations will be that big an issue.
Regardless, I think we need to have the comment system play out before
we can make any final judgement on this, as we (or I at least) don't
know if this will be an issue at all or not.
>
> --- when someone tries to add a comment in PHP docs, a new page
> appears, containing explanations about what may or may not be written
> in comments. Not bad ?
>
I have already added a notice that explains a bit about what the
comments section is intended for. If this is not enough, then I'll
figure out some way to add some additional info inside the comment
system itself.

With regards,
Daniel.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: [Httpd Wiki] Update of "DocsCommentSystem" by DanielGruno [ In reply to ]
Le 23 mai 2012 à 09:40, Daniel Gruno a écrit :

> On 05/23/2012 09:26 AM, Lucien Gentis wrote:
>> Hello everybody,
>>
>> Le 23 mai 2012 à 06:28, Apache Wiki a écrit :
>>
>>>
>>> == Questions for further discussion ==
>>> * Should translations have their own separate discussion threads,
>>> or should they show the same thread as the English version?
>>
>> A few days ago, httpd comment system was compared to PHP docs comment
>> system.
>>
>> Just a few remarks :
>>
>> --- all PHP docs comments are in english and are the same in all
>> translated pages : I should have rather seen french comments in french
>> pages, turkish comments in turkish pages . . . , but on the other
>> hand, if there is only one thread (in english) for each comment, it
>> could be seen in all translated pages by all readers, which, I think,
>> would be better for content related comments, but not for comments
>> about a translation problem, for example.
>> Could it be possible for a 'commenter' to make a choice between adding
>> his/her comment only for the considered page, or for all languages pages ?
> Everything is possible on the Interweb, but I think this might be a tad
> complex.
> As Rich pointed out, we will most likely be deleting comments if they
> are implemented, invalid or off-topic, so I don't think that having
> people remark on translations will be that big an issue.
> Regardless, I think we need to have the comment system play out before
> we can make any final judgement on this, as we (or I at least) don't
> know if this will be an issue at all or not.
>>
>> --- when someone tries to add a comment in PHP docs, a new page
>> appears, containing explanations about what may or may not be written
>> in comments. Not bad ?
>>
> I have already added a notice that explains a bit about what the
> comments section is intended for. If this is not enough, then I'll
> figure out some way to add some additional info inside the comment
> system itself.

Oh yes, I didn't saw it yet and it's great.

A suggestion : perhaps the three objects (Notice frame, "Post a new comment" and "Log in/Log out" buttons) should be duplicated at the bottom of the page, in case comments cover several pages.

>
> With regards,
> Daniel.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>


Lucien Gentis
SIRET
Faculté de Médecine - Nancy
lucien.gentis@univ-lorraine.fr
03 83 68 30 62