On Jan 7, 2008 10:45 PM, John David Anderson (_psychic_) <[EMAIL PROTECTED]> wrote: > > > 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. >
Yes, PHP.net works well with that, i have to admit, but there is also much trash and really really old examples that one should never adopt. But most of the times it is okay.. I just emphasized the "comments vs. documentation"-theory because there may probably be unhealthy amounts of "it duz nut wurk!" posts. :-) > > 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. > Whoops, misunderstanding: Blogs as in "static, but commentable, content". A page that is written/posted and never looked back at (and only maintainable by the owner). Like a bakery article.. you create it and if you don't edit it, it will be the way it was forever... > > 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. > Hmm.. yeah.. since the pages are kept up to date by you and others this may be not that big of an issue then. > > > 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. > Great > > 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. > Okay, got ya.. this idea above was more directed towards an Bakery-like system where everyone could create pages on their own. In that case it would be possible that a user leaves or forgets about it. Looking forward. --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
