httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rich Bowen <>
Subject Re: Questions for further discussion about Documentation commentary system
Date Wed, 09 May 2012 13:52:06 GMT

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

View raw message