Hmmm... I have a problem with a "comment"-function. Comments encourage discussions - Discussions have nothing 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. 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). 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.. 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. 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? - Kjell Bublitz On Jan 7, 2008 4:01 PM, John David Anderson (_psychic_) <[EMAIL PROTECTED]> wrote: > > How can you recruit maintainers and editors when the current docs team > can't do that? I have some great help from great people, but no one > seems to have the time to commit on a regular basis. A wiki represents > a much higher maintenance cost, something I doubt you can muster. The > core team definitely can't swing it, from what I can tell right now. > > Besides, there are already 170+ pages of docs for this "transition > phase." The tempdocs.cakephp.org site has been publicized on this list > and is linked to from the 1.2.x branch home.ctp default view. There > are a low amount of active docs tickets - what exactly will a wiki > bring to the table (content-wise) that we don't already have a good > start on? > > We're also completing testing a tool right now that allows people to > contribute more easily - something that can be commented, submitted > to, etc. I'm moving the material from tempdocs over to this new system > that already does much of what you're asking for here, without the > fatal disadvantages of a wiki. > > There's almost no chance a wiki will receive official CakePHP support, > especially from me. It didn't work, the Bakery does work, and we're > 90% of the way committed with another custom home-grown tool that is > really looking to fit our needs. I don't want to dull your enthusiasm, > I just want to channel it into something that will work better. If > you'd like to improve the documentation for CakePHP, please contact me. > > Stay tuned, I hope to have something to show soon. > > -- John > > > On Jan 7, 2008, at 5:46 AM, Kjell Bublitz wrote: > > > > > Hi list and maintainers! > > > > As the topictitle says, i would like to see a wiki-revival. > > > > I like the bakery, but since we are all desperate for docs, good > > up-to-date examples and practices it would help the community if we > > had a Wiki again! > > > > I am also not for a Wiki that is swarmed by newcomers asking for help > > on the 101 but i also dont want to explain stuff more than twice (in > > chats or wherever), and i myself dislike hunting for "good" blog > > entries or the "right topic" in the groups. Can be very frustrating at > > times... you gotta admit that. > > > > I know from the past that the Wiki was a mess, but thats where we need > > to recrute/name moderators (an open sub-team maybe). You could count > > me in for that. > > > > A wiki version of the docs is absolutely necessary in such a long > > transition phase. > > > > There are so many changes and most devs want to use and learn 1.2 > > already. > > > > The docteam then could adopt the writings and compile it, readers > > could download/export a current draft, subscribe to pages using rss, > > etc .. > > > > But for this to work the general structure needs to be layed out from > > start (bakery is a good example: version info, type). > > > > With a well categorized layout we should be able to reach a good > > amount of quality! The old Wiki had no structure at all... > > > > Maybe in the beginning we should give all approved contributers from > > bakery write access to the wiki only. > > > > That would sort out the problem of having everybody creating pages > > at will. > > > > Later on we can remove this restriction after a good amount is > > ported/created within the new setup and we give everyone write access. > > > > Who wouldn't want the Manual Pages to be reviewed? :-) > > > > What you think? > > > > Best! > > Kjell "m3nt0r" Bublitz > > > > > > PS: please use mediawiki if you give it a (second) shot. The old > > wiki-soft was crap.. ^^ > > > > > > > > > > > --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
