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