Return-Path: X-Original-To: apmail-httpd-docs-archive@www.apache.org Delivered-To: apmail-httpd-docs-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 51BF0908C for ; Wed, 9 May 2012 13:52:38 +0000 (UTC) Received: (qmail 33894 invoked by uid 500); 9 May 2012 13:52:38 -0000 Delivered-To: apmail-httpd-docs-archive@httpd.apache.org Received: (qmail 33836 invoked by uid 500); 9 May 2012 13:52:38 -0000 Mailing-List: contact docs-help@httpd.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: docs@httpd.apache.org List-Id: Delivered-To: mailing list docs@httpd.apache.org Received: (qmail 33828 invoked by uid 99); 9 May 2012 13:52:38 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 09 May 2012 13:52:38 +0000 X-ASF-Spam-Status: No, hits=2.2 required=5.0 tests=HTML_MESSAGE,RCVD_IN_DNSWL_LOW,SPF_NEUTRAL X-Spam-Check-By: apache.org Received-SPF: neutral (nike.apache.org: local policy) Received: from [209.85.212.169] (HELO mail-wi0-f169.google.com) (209.85.212.169) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 09 May 2012 13:52:29 +0000 Received: by wibhn14 with SMTP id hn14so1591608wib.0 for ; Wed, 09 May 2012 06:52:09 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=from:mime-version:content-type:subject:date:in-reply-to:to :references:message-id:x-mailer:x-gm-message-state; bh=y4W7IRBYowKmWezewG8iD4Rihq5K92Lnbbwh6/CPaFM=; b=HegOA5AthYbWUk+0EUCCotGSUTuIcAkqN03gkG8sMocsf0ER4RluVKEFvqu2NLi9tY oQseEgwqRYgOwk98UGELO7a/mAT0A6Z9wmCEnpDXNWEiBRyEPKYhYgF6g7dwome7yiCF d3QM7rc5BuHIIOaP+kX603NlF5NwwEHfwnie1CaDR44j3sYmDBx2cqnDNdvIQF7/tNTz C3VkMGbRmwXRYf8TGzhCRKSnUC5zrvJvlzC1Wp5a8KVBCtupof/Ah6ZiGXr+z8ULyEtA xyjmguEGDwC+aXIY0BCH3z780m+qHR9t3hYFjuxJ1EJztl1Y2LSReAqGAQFsBOOdLT/e nnMA== Received: by 10.50.40.232 with SMTP id a8mr1606020igl.18.1336571528895; Wed, 09 May 2012 06:52:08 -0700 (PDT) Received: from [192.168.0.198] (74-131-224-250.dhcp.insightbb.com. [74.131.224.250]) by mx.google.com with ESMTPS id d5sm3319112iga.15.2012.05.09.06.52.07 (version=TLSv1/SSLv3 cipher=OTHER); Wed, 09 May 2012 06:52:07 -0700 (PDT) From: Rich Bowen Mime-Version: 1.0 (Apple Message framework v1257) Content-Type: multipart/alternative; boundary="Apple-Mail=_05EA46E6-978E-4673-A65D-F283B6E09CBA" Subject: Re: Questions for further discussion about Documentation commentary system Date: Wed, 9 May 2012 09:52:06 -0400 In-Reply-To: <90E76ABC-29E3-4AB1-9213-755051C218EA@medecine.uhp-nancy.fr> To: docs@httpd.apache.org References: <90E76ABC-29E3-4AB1-9213-755051C218EA@medecine.uhp-nancy.fr> Message-Id: <1D8C4C3B-00C8-48E9-A09F-869C1F50A558@rcbowen.com> X-Mailer: Apple Mail (2.1257) X-Gm-Message-State: ALoCoQlI1JdnlDeBtjMMaP5YP+f4I0563nzXu4BRvcfa49NRdF2k/iVdV/ribI3smfGFpKhFAZ/7 --Apple-Mail=_05EA46E6-978E-4673-A65D-F283B6E09CBA Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset=iso-8859-1 On May 9, 2012, at 7:35 AM, Lucien Gentis wrote: >=20 > 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@rcbowen.com :: @rbowen rbowen@apache.org --Apple-Mail=_05EA46E6-978E-4673-A65D-F283B6E09CBA Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset=iso-8859-1

  • 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@rcbowen.com :: = @rbowen
rbowen@apache.org

= --Apple-Mail=_05EA46E6-978E-4673-A65D-F283B6E09CBA--