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

Mailing List Archive: Apache: Docs

Questions for further discussion about Documentation commentary system

 

 

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


lucien.gentis at medecine

May 9, 2012, 4:35 AM

Post #1 of 7 (566 views)
Permalink
Questions for further discussion about Documentation commentary system

Hello everybody,

Should translations have their own separate discussion threads, or should they show the same thread as the English version?
I think each translation should have their own separate discussion threads, because I can't imagine a french discussion appended to a turkish or korean document ; it would probably get no answer !
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?
The discussion must appear in each version it applies to.
Should we do regular XML exports of the discussion, and if so, where should we store it?
A good question ! :-) Let's go to the next one (this only means I have no answer)
Who will moderate, and how will new moderators be picked?
I think moderators should be people who actually write the docs, because in addition to moderation, probably they will have to answer complex questions.
As a translator (and I only speek for my own case), I probably (and even surely) won't be able to answer all questions.
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?
I think that, as a test you could allow everybody to comment, at least in the beginning, and see as time passes if it is appropriate.
How to moderate : I think all comment that's related to the subject must be accepted.

Lucien


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


rumble at cord

May 9, 2012, 5:07 AM

Post #2 of 7 (536 views)
Permalink
Re: Questions for further discussion about Documentation commentary system [In reply to]

On 09-05-2012 13:35, Lucien Gentis wrote:
> Hello everybody,
>
> * Should translations have their own separate discussion threads, or
> should they show the same thread as the English version?
>
> I think each translation should have their own separate discussion
> threads, because I can't imagine a french discussion appended to a
> turkish or korean document ; it would probably get no answer !
>
A valid point, and that's also what we're doing currently in the testing
phase.
> * 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?
>
> The discussion must appear in each version it applies to.

This is a bit more tricky than that. If we were to attempt to have the
discussion "appear in each version it applies to", the closest we could
get would be to merge it on a per-module basis, so that fx. core.xml
would have the same discussion thread in 2.2 and 2.4. This could however
cause a lot of trouble, since 2.4 has upgrades like If, Else and so on,
which do not appear in 2.2. So I think our best option is to keep the
versions separate. A more general problem with this is that Google
continues to point to our 2.0 documentation whenever someone comes here
for help, so they'll never hit the discussion threads. If we could
Redirect those requests to our 2.2 or 2.4, then we'd have way more
people using our current docs and participating in the discussions. But
perhaps that's a totally different discussion.

>
> * Should we do regular XML exports of the discussion, and if so, where
> should we store it?
>
> A good question ! :-) Let's go to the next one (this only means I have
> no answer)

I think we can postpone a resolution on this matter for a while, since
it doesn't look like Disqus is going bankrupt just yet.

>
> * Who will moderate, and how will new moderators be picked?
>
> I think moderators should be people who actually write the docs, because
> in addition to moderation, probably they will have to answer complex
> questions.
> As a translator (and I only speek for my own case), I probably (and even
> surely) won't be able to answer all questions.

I think the discussions are more of a "help yourself and others" type of
discussion, where we hope other readers will be able to help out, and
not just the docs people working 24/7 to answer questions. Regarding who
should be moderators, I think that by allowing others from the docs@
list to become moderators, we would lower the bar for participating, and
wouldn't require everyone to sign an ICLA just to moderate comments.

>
> * 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?
>
> I think that, as a test you could allow everybody to comment, at least
> in the beginning, and see as time passes if it is appropriate.
> How to moderate : I think all comment that's related to the subject must
> be accepted.
>

I agree with this - let's see if spam or ill will is actually an issue
before we decide on this :)

With regards,
Daniel.

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


lucien.gentis at medecine

May 9, 2012, 6:39 AM

Post #3 of 7 (527 views)
Permalink
Re: Questions for further discussion about Documentation commentary system [In reply to]

Le 9 mai 2012 à 14:07, Daniel Gruno a écrit :

> On 09-05-2012 13:35, Lucien Gentis wrote:
>> Hello everybody,
>>
>> * Should translations have their own separate discussion threads, or
>> should they show the same thread as the English version?
>>
>> I think each translation should have their own separate discussion
>> threads, because I can't imagine a french discussion appended to a
>> turkish or korean document ; it would probably get no answer !
>>
> A valid point, and that's also what we're doing currently in the testing
> phase.
>> * 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?
>>
>> The discussion must appear in each version it applies to.
>
> This is a bit more tricky than that. If we were to attempt to have the
> discussion "appear in each version it applies to", the closest we could
> get would be to merge it on a per-module basis, so that fx. core.xml
> would have the same discussion thread in 2.2 and 2.4. This could however
> cause a lot of trouble, since 2.4 has upgrades like If, Else and so on,
> which do not appear in 2.2. So I think our best option is to keep the
> versions separate.

I agree.
I only meant that if a comment is 2.2 and 2.4 related, it should appear in each version.
But how could it be achieved ?
Each time a moderator validates a comment in 2.4 docs for example, he should verify
if it's also 2.2 related, and if it is, port it to 2.2
This could lead to big work for the moderators.

> A more general problem with this is that Google
> continues to point to our 2.0 documentation whenever someone comes here
> for help, so they'll never hit the discussion threads. If we could
> Redirect those requests to our 2.2 or 2.4, then we'd have way more
> people using our current docs and participating in the discussions. But
> perhaps that's a totally different discussion.
>
>>
>> * Should we do regular XML exports of the discussion, and if so, where
>> should we store it?
>>
>> A good question ! :-) Let's go to the next one (this only means I have
>> no answer)
>
> I think we can postpone a resolution on this matter for a while, since
> it doesn't look like Disqus is going bankrupt just yet.
>
>>
>> * Who will moderate, and how will new moderators be picked?
>>
>> I think moderators should be people who actually write the docs, because
>> in addition to moderation, probably they will have to answer complex
>> questions.
>> As a translator (and I only speek for my own case), I probably (and even
>> surely) won't be able to answer all questions.
>
> I think the discussions are more of a "help yourself and others" type of
> discussion, where we hope other readers will be able to help out, and
> not just the docs people working 24/7 to answer questions. Regarding who
> should be moderators, I think that by allowing others from the docs@
> list to become moderators, we would lower the bar for participating, and
> wouldn't require everyone to sign an ICLA just to moderate comments.

Yes, like you say below, let us see what types of content are within the comments.


>
>>
>> * 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?
>>
>> I think that, as a test you could allow everybody to comment, at least
>> in the beginning, and see as time passes if it is appropriate.
>> How to moderate : I think all comment that's related to the subject must
>> be accepted.
>>
>
> I agree with this - let's see if spam or ill will is actually an issue
> before we decide on this :)
>
> With regards,
> Daniel.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe [at] httpd
> For additional commands, e-mail: docs-help [at] httpd
>


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


rbowen at rcbowen

May 9, 2012, 6:44 AM

Post #4 of 7 (528 views)
Permalink
Re: Questions for further discussion about Documentation commentary system [In reply to]

On May 9, 2012, at 9:39 AM, Lucien Gentis wrote:

> I agree.
> I only meant that if a comment is 2.2 and 2.4 related, it should appear in each version.
> But how could it be achieved ?
> Each time a moderator validates a comment in 2.4 docs for example, he should verify
> if it's also 2.2 related, and if it is, port it to 2.2
> This could lead to big work for the moderators.


Sure, but that's what we do now already. When we apply a doc change, we have to consider what branches need the change, and make it there, otherwise the branches drift out of sync, creating more work later.

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache


rbowen at rcbowen

May 9, 2012, 6:52 AM

Post #5 of 7 (527 views)
Permalink
Re: Questions for further discussion about Documentation commentary system [In reply to]

On May 9, 2012, at 7:35 AM, Lucien Gentis wrote:

>
> 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?
> The discussion must appear in each version it applies to.

Yes, I think I agree, but one still needs to consider whether a comment applies to other branches as well.
> Should we do regular XML exports of the discussion, and if so, where should we store it?
> A good question ! :-) Let's go to the next one (this only means I have no answer)

If it's easy to grab exports, there's no harm in doing so. But I don't feel that comments should be considered long-term things. Comments should be either integrated into the documentation, or they should be cleaned up. I don't see the comments system as a discussion forum - it's suggestions for improvement and clarification of the docs. I don't really care to see people use this as a support forum. We have several of those, and we should encourage people to go to them.
> Who will moderate, and how will new moderators be picked?
> I think moderators should be people who actually write the docs, because in addition to moderation, probably they will have to answer complex questions.
> As a translator (and I only speek for my own case), I probably (and even surely) won't be able to answer all questions.

We're all moderators.

A select group should be there to clean up spam. Beyond that, "moderation" consists of determining which comments are beneficial to the docs (ie, suggestions for improvement and clarification) and which are support requests that should be redirected.

The goal of adding comments is *not*, as I say above, to create a support forum. See the PHP documentation for an example of where this is done well. We should not encourage people to use this as a chat/discussion/support forum. That will lead to madness. Can you imagine 939 distinct discussion forums in our documentation? (That's how many distinct doc pages we have that could potentially have this feature.)


> 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?
> I think that, as a test you could allow everybody to comment, at least in the beginning, and see as time passes if it is appropriate.
> How to moderate : I think all comment that's related to the subject must be accepted.


The approach is:

* Remove comments that are spam, off-topic, or merely comments like "thank you".
* Determine if a comment warrants a change to the documentation. If so, make that change.
* Purge the comment.

Brief conversations can be had if they clarify where the commenter was going with it.

I don't see comments remaining as a long-term part of any given document, which is why the XML export bit seems unnecessary, and possibly even harmful in that it sets an expectation of permanence.

Again, see the PHP docs for a place where this is done well.





--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache


lucien.gentis at medecine

May 9, 2012, 7:13 AM

Post #6 of 7 (529 views)
Permalink
Re: Questions for further discussion about Documentation commentary system [In reply to]

Le 9 mai 2012 à 15:44, Rich Bowen a écrit :

>
> On May 9, 2012, at 9:39 AM, Lucien Gentis wrote:
>
>> I agree.
>> I only meant that if a comment is 2.2 and 2.4 related, it should appear in each version.
>> But how could it be achieved ?
>> Each time a moderator validates a comment in 2.4 docs for example, he should verify
>> if it's also 2.2 related, and if it is, port it to 2.2
>> This could lead to big work for the moderators.
>
>
> Sure, but that's what we do now already. When we apply a doc change, we have to consider what branches need the change, and make it there, otherwise the branches drift out of sync, creating more work later.

All the thing depends on the number of comments to handle per day, hour,..., minute ?

More seriously, I don't think there will be so much, but it's difficult to evaluate their number.

>
> --
> Rich Bowen
> rbowen [at] rcbowen :: @rbowen
> rbowen [at] apache
>
>
>
>
>
>


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


rbowen at rcbowen

May 9, 2012, 7:22 AM

Post #7 of 7 (529 views)
Permalink
Re: Questions for further discussion about Documentation commentary system [In reply to]

On May 9, 2012, at 10:13 AM, Lucien Gentis wrote:

> All the thing depends on the number of comments to handle per day, hour,..., minute ?
>
> More seriously, I don't think there will be so much, but it's difficult to evaluate their number.

I don't think that there will be a large volume of legitimate comments, but, yes, we're just making up numbers right now, so it's very hard to know what to expect.

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache

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.