On Jan 7, 2008, at 2:31 PM, Kjell Bublitz wrote:
> > Hmmm... I have a problem with a "comment"-function. > > Comments encourage discussions - Discussions have nothing to do with > documentation. Like rtconner said, php.net's documentation has really benefitted from comments. It allows people to suggest ways to do things, examples, relevant code snippets or notes about applicable plugins and classes. It *does* have to do with documentation. > If theres a comment function it is almost as good as an invitation for > beginners to ask right away, rather than to read on their own. We all > know that well enough :) So a comment section kinda destroys the > purpose of the system. Docs shouldn't be yet another forum or chat. > Asking is okay, but there should be no need to ask if the page keeps > being maintained. Comments that ask for support will probably be removed. Haven't made a decision on that yet. I don't mind people posting queries and solving gotchas in the manual though. > Just take an simple blog entry for example (or bakery for that > matter): Good infos scattered all over the place and no one can or > wants to break it down for future reference (ie: add to the original > post, keep things fresh, based on discussion outcome). I don't see how personal blogs really directly relate to the official documentation effort. We always appreciate the attention, but there's no way we can catalog or review all that content. That's really not in the scope of this project. > But that's just natural: Why add something that has been explained > somewhere in the comments? The problem is the result after some time > has passsed. The page is cluttered, new visitors just keep asking for > help and more details, and others don't know which snippet from all > the comments now really works.. I disagree with how you paint this picture. It seems like an over- exaggeration to me. A separated place in the manual for comments has been well done in the past, I don't think it'll be as disorganized as you think. > So how about this (in addition to your system): > > Rather than having a "Comment" section, we have a "Contribute" section > below the article. > > - Any submission is appended (as proposal) to the page for a certain > period (2 weeks) for public review (maybe with votes). > - The pageowner can then approve or deny the new submission: Approval > means that he adds it the original content. > - Once a submission is accepted and added to the page it is removed > from the contribute section below. This is essentially what we already have in the works, in addition to allowing comments. All suggestions on new sections and changes to content are reviewed by myself or my team. > Now how to deal with "dead pages / missing owner"? > Some ideas: > > If the pageowner does not react within the 2 weeks period... > A) ... an automated email notifys the siteadmin to take over. > B) ... the ownership is turned over to the last contributer. > C) ... the notified admin names a new pageowner > > Aditionally: "report dead page", "report spam", "mark as outdated" > > What you think? There won't really be any dead pages or ownerless pages. All content will be managed by myself or delegated to docs team members. -- John --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Cake PHP" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/cake-php?hl=en -~----------~----~----~----~------~----~------~--~---
