Contributions vs. Criticism - Was: Cake 1.2
On Jan 13, 2007, at 2:11 AM, Sergei wrote: Canglan писал(а): I'm actually more concerned about the documentation. It's not an easy task yes, but if the documentation can be really enhanced then it will boost the Cakephp community by quite a large margin. :-) Indeed. Cake's documentation sucks compared to Symfony's one, for example. I've learned about some things only from this group. Im not even talking about 1.2. God knows when it will be fully documented. *Voice heard from the clouds* Verily, verily I say unto you: not until the API is like unto a rock and solid unto me, will ye yet read those words! *Clouds close up* Seriously though, 1.2 manual is in the works, and wont be released until 1.2 code is no longer a moving target. I don't an absence of docs for a developer's release is out of the question. Let the API and the changelog guide you. Interesting that you compare our documentation effort to Symfony's. I took a *quick* look just to get an idea of how we compare: CakePHP 110% Volunteer 5 Screencasts 2 Manual Tutorials, 40-50 Bakery Tutorials Online Manual, 23 Chapters, 141 Page PDF Symfony Sponsored by a French web agency 2 Screencasts 2 Official Tutorials Online Manual, 13 chapters, 129 Pages Manual, 170 Pages tutorials (Basically about 170 pages of How to... sections) disclaimerUnless I've missed something extremely significant, please don't make an effort to correct me here. This was a ten minute look, which is more that a first time user will often spend./ disclaimer Since many Symfony tutorials appear in their Symfony Book manual, and ours appear in the Bakery, I'd say that at least the numbers look pretty even. Those numbers look even better when you consider that most tutorials are community contributed (and team approved), and the remainder of the docs are a *volunteer* effort. I have no idea if the Symfony docs people get paid, but I sure don't, and having a sponsor must lighten their load in some places. Frankly, I'm tired of people making complaints about the documentation (or anything else, for that matter). Not because they are perfect, because they are truly far from that. Mostly because any criticism (especially vague criticism) that isn't followed with some effort to help is both useless and insulting. It's like walking into a friend's open party and complaining about the food–how its not as good as the company party across the street–and threatening to leave if the volunteers in the kitchen don't step it up a notch. I think Dr. Sani's comments are spot on. Welcome to our party. If you'd like to make something better, we need your help. Log a ticket. Contact one of us to see where your talents are best focused. I've fielded many requests from people wishing to help out with the docs, and in almost two years of my Cake efforts, there's only been a handful of people who have actually followed through. Saying you're willing to help and actually putting pen to paper has been a chasm a mile wide in my experience. And while blogging about CakePHP or starting your own efforts is helpful in a way, isn't better to contribute officially so your work is coming from the source? Why not put all that effort into one place, rather than spread across the Internet? Here's hoping the new year will bring in more consideration and collaboration... before criticism. -- John --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Cake PHP group. To post to this group, send email to cake-php@googlegroups.com 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 -~--~~~~--~~--~--~---
Re: Contributions vs. Criticism - Was: Cake 1.2
I can understand your concern John. However one thing to notice is that, most of the people who complain are the people who are not so familiar with CakePHP (and that includes myself). Even if we are willing to help, we lack the guts. In my case, I have had a look at CakePHP more than a year ago, then I was turned downed because the documentation back then was horrible (no offense here). Now, I have some experience with Ruby on Rails and Code Igniter, I decided to give CakePHP another try. It's glad to see that the documentation is much better than it was a year ago, e.g. the resource in bakery is brilliant. However, the manual still needs a lot of work. Not that I am complaining, I praise the work you guys have done, for an open source project like CakePHP it's really really impressive. However, what if the lead developers pause the code development for a while and transfer the effort into making a more complete manual? I believe this will only do good for the project and the community. No one other than the developers themselves knows exactly the ins and outs of the system. By documenting the whole system deeply, you're actually reviewing the project, and that will probably give you some hints on what part of the project (in terms of coding) might need to be enhanced or modified, it's a win-win situation don't you think so? =) That being said, I am not suggesting that people should always expect someone else to spoon feed them, in fact, I wish that a better manual to bring more people into our community and therefore more things can be done. Just my 2 cents. - Fred --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Cake PHP group. To post to this group, send email to cake-php@googlegroups.com 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 -~--~~~~--~~--~--~---
Re: Contributions vs. Criticism - Was: Cake 1.2
However, what if the lead developers pause the code development for a while and transfer the effort into making a more complete manual? I believe this will only do good for the project and the community. Then many people will start complaining about the lack of progress of the code. There is just much work that needs to be done. If you start focusing on another aspect, something else will suffer. We need to figure out what is most important for the devs to do: a job that only they can do (code) or a job that they, or any volunteer can do (docs) ? No one other than the developers themselves knows exactly the ins and outs of the system. By documenting the whole system deeply, you're actually reviewing the project There are several devs. i'm damned sure that some of them aren't really following what another is doing. not that that's a problem. Also, we have many users that like to spit through the cake code in their free time to learn about both the inner workings as of the api (how to work with it) of the framework, people like this can perfectly do docs. The best practice -imho- would be to let volunteers work on docs, but be guided by the devs, so that they can make some additions, fixes,.. where necessary without using too much time that could be used for the job that only they can do (development) And your logic is correct: people that want to do docs must learn the code.. a win-win indeed. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Cake PHP group. To post to this group, send email to cake-php@googlegroups.com 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 -~--~~~~--~~--~--~---
