Apache web server documentation development list

Apache Wiki | 23 May 2012 06:28

[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

(Continue reading)

headers

Lucien Gentis | 23 May 2012 09:26

Re: [Httpd Wiki] Update of "DocsCommentSystem" by DanielGruno

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

03 83 68 30 62

headers

Daniel Gruno | 23 May 2012 09:40

Re: [Httpd Wiki] Update of "DocsCommentSystem" by DanielGruno

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.

headers

Lucien Gentis | 23 May 2012 10:12

Re: [Httpd Wiki] Update of "DocsCommentSystem" by DanielGruno

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 <at> httpd.apache.org
For additional commands, e-mail: docs-help <at> httpd.apache.org

Lucien Gentis

SIRET

Faculté de Médecine - Nancy

lucien.gentis <at> univ-lorraine.fr

03 83 68 30 62