Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Apache: Docs

[Httpd Wiki] Update of "DocsCommentSystem" by DanielGruno

 

 

Apache docs RSS feed   Index | Next | Previous | View Threaded


wikidiffs at apache

May 22, 2012, 9:28 PM

Post #1 of 4 (450 views)
Permalink
[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?action=diff&rev1=5&rev2=6

* 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.
+ The currently proposed solution is to use a new comment system developed for the Apache HTTP Server Project. For the time being, this solution is being hosted off-site, but plans are in motion to host this within the ASF.

=== 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.
+
+ The backend system itself is run by Lua scripts on Apache 2.4 with mod_pLua and a MySQL database. Source codes can be found at http://c.apaste.info/source/

=== 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.
@@ -24, +26 @@

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 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. 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 that have links in them 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 the system before they can comment.
+
+ If anyone wants to be a moderator for the test run, do speak up. If/when this migrates to infra, the current plan is to make all Apache committers moderators and manage this through LDAP. More info will follow as it becomes available.

=== 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.

=== 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.
+ The comment system supports an XML export of comments (which can be found [[http://c.apaste.info/export.lua?site=httpd|here]]). 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 service is discontinued or if/when we need to move to the Infra server instead.

== 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?
+ * Who will moderate, and how will new moderators be picked? (If this moves to infra, then all Apache committers will likely be moderators, and people can then sign up to receive notifications on a per-project basis)
* 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 [at] httpd
For additional commands, e-mail: docs-help [at] httpd


lucien.gentis at medecine

May 23, 2012, 12:26 AM

Post #2 of 4 (420 views)
Permalink
Re: [Httpd Wiki] Update of "DocsCommentSystem" by DanielGruno [In reply to]

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 ?

--- 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 ?

Regards

Lucien

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


wikidiffs at apache

May 26, 2012, 6:00 AM

Post #3 of 4 (418 views)
Permalink
[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=6&rev2=7

Comment:
Answering a few questions

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. 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 will, in general, be allowed through without pre-approval. Comments with hyperlinks in them will require approval from a moderator before they are shown on the site. The comment system itself has a built-in touring test that should get rid of most of the spam (we have yet to receive any spam).

- Comments that have links in them 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 the system before they can comment.
+ Any Apache committer that wishes to become moderator can do so by logging onto the comment system (see the "log in" link in each comment section) using their Apache committer id and password. Since this will be managed by the LDAP service, any new committers will automatically gain this right without any previous manual work done by the sysadmins.

- If anyone wants to be a moderator for the test run, do speak up. If/when this migrates to infra, the current plan is to make all Apache committers moderators and manage this through LDAP. More info will follow as it becomes available.
+ One or more key figures will be appointed comment administrators, and may use this role to manage/verify non-Apache people that wish to become moderators.
+
+ Verified people or moderators will have their comments flagged with a small feather to show that their identity has been verified by Apache.
+
+ Moderators and admins can click on the "moderate" link in a comment section to go to the moderator panel of the system, where they can review the latest activity, track specific poster origins and perform tasks such as removing all posts made from a specific poster or ban an IP/origin from posting on this site or any other that uses the comment system. Comment admins can furthermore review activity logs to see if any moderator or poster has been behaving strangely, and act accordingly.

=== 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.

=== Comment Exports ===
- The comment system supports an XML export of comments (which can be found [[http://c.apaste.info/export.lua?site=httpd|here]]). 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 service is discontinued or if/when we need to move to the Infra server instead.
+ The comment system supports an XML export of comments (which can be found [[http://c.apaste.info/export.lua?site=httpd|here]]). At this time, there doesn't seem to be any pressing need for this, if we move to infra anyway.

== 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? (If this moves to infra, then all Apache committers will likely be moderators, and people can then sign up to receive notifications on a per-project basis)
- * 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 [at] httpd
For additional commands, e-mail: docs-help [at] httpd


wikidiffs at apache

Jun 9, 2012, 1:06 AM

Post #4 of 4 (396 views)
Permalink
[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=7&rev2=8

* 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 a new comment system developed for the Apache HTTP Server Project. For the time being, this solution is being hosted off-site, but plans are in motion to host this within the ASF.
+ The currently proposed solution is to use a new comment system developed for the Apache HTTP Server Project.
+
+ For the time being, this solution is being hosted off-site, but plans are in motion to host this within the ASF.

=== 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.

- The backend system itself is run by Lua scripts on Apache 2.4 with mod_pLua and a MySQL database. Source codes can be found at http://c.apaste.info/source/
+ The backend system itself is run by Lua scripts on Apache 2.4 with mod_pLua and a MySQL database. Source codes are located in the infra repository.

=== 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.

+ === Branches ===
+ Each branch (2.2, 2.4 and trunk) will have its own separate comments. We may choose to copy or move comments from one branch to another, and if this is deemed necessary, a plugin for the comment system will be set up to allow for easy movement between branches.
+
=== 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.
+ The various translations will, together with the English version, share the same discussions. Threads will be based on the page that is being shown, not the language it is being shown in.
+ Comments about translations (typos etc) will be tolerated, but all other communication should be in English, so we have a better chance of moderating and following up on comments.

=== Moderating comments ===
- Comments will, in general, be allowed through without pre-approval. Comments with hyperlinks in them will require approval from a moderator before they are shown on the site. The comment system itself has a built-in touring test that should get rid of most of the spam (we have yet to receive any spam).
+ Comments will, in general, be allowed through without pre-approval. Comments with hyperlinks in them will require approval from a moderator before they are shown on the site. The comment system itself has a built-in Turing test that should get rid of most of the spam (we have yet to receive any spam).

Any Apache committer that wishes to become moderator can do so by logging onto the comment system (see the "log in" link in each comment section) using their Apache committer id and password. Since this will be managed by the LDAP service, any new committers will automatically gain this right without any previous manual work done by the sysadmins.

@@ -43, +49 @@

The comment system supports an XML export of comments (which can be found [[http://c.apaste.info/export.lua?site=httpd|here]]). At this time, there doesn't seem to be any pressing need for this, if we move to infra anyway.

== Questions for further discussion ==
+ There are no outstanding questions. If you have one, please add it.
- * 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?


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd

Apache docs RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.