I agree comments CAN BE great! !!!! BUT !!!!
Should be left to the professionals. Mr Cake Baker (sorry if someone has that name...not intentional) who has 2 days use with Cake thinking he is an expert posting bad comments everywhere adding misguided information helps no-one. With the framework every situation is different, what works for 1 may infact not work for someone else. Who is to say what a basic example of usage is (other than the developers)? I think the examples in the cookbook provide enough details to get a person started. More complex / specific question posted here seem to be working quite fine as almost every question asked here gets a answer if not a dozen. There are a dozen if not more cake guys out there who have sites / personal blogs with loads of tips / guides / code that I have bookmarked in my favs and I use them as great resources. Most allow questions and comments for each section where they answer their own questions. Sure I have to jump around and look for stuff but you know what. If it take me a few mins or an hour to find correct quality info then it beats a day working with faulty comments, bad examples. There is no perfect solution but part of the responsibility is on us, the user to take the time to find / make / show these things on our own and let the developers develop. Maybe a list of CakePros which is a list of Cake users with proven experience / knowledge with links to their sites?(Miles J, John Anderson, ClassOutfit, Dr.Lobato, Euromark, Cricket to name a few who 99% of the time in my opinion solve almost any issue I have ever seen!) As for developers reviewing comments....I would rather the developers focus on the code, not the comments. I would rather my framework be as efficient as possible and knowing they are hard at work doing that is of more importance then having to break up their day to monitor comments. But that's just me :) Bake away! -----Original Message----- From: LunarDraco [mailto:[email protected]] Sent: Monday, January 24, 2011 5:26 PM To: CakePHP Subject: Re: CakePHP 1.3.7 released I do NOT see comments on the cakephp documentation to be valuable. I think comments like php.net are great when your talking about how to use a function. Most of the content of the cakephp book is how to use the framework a little bit more extensive than a sequence of function calls. This is where comments really don't help, the comments are either not complete enough to really help anyone or they are misleading and end up confusing more than they help. Examples of use with decent explanations are extremely valuable, and should be made part of the documentation, and I think the authors of the book have been doing a great job at this in recent years. These examples tend to take more effort to put together. Submitted to git where the concepts can also be reviewed by the architects of the framework and verified against best practice. Best practice is another issue when you step past the function to the framework. A lot of the comments go against best practice because it takes to much effort to explain how to do it correctly in a comment. This is why we see way too much code in the controller that should be in the model. I'm pretty sure for the most part we can all read an API for a function. There are plenty of comments on usage of specific functions and parameters in the google groups. A good number with links back to the documentation. If you really want to see how to use a function take a peek at the test case. The documentation needs more real examples that focus on solving a specific problem, or best practice on using a specific part of the framework. This is where we can really add to the value of the documentation. Another problem with comments is when you go to convert or output your documentation in different formats like PDF etc. You generally don't get the comments which might show one or two good examples, or you get all the comments regardless of how relevant they might be. I vote for using a tool like sphinx for documentation. Using git and community contributed commits to enhance the documentation. And I vote for keeping comments and questions in the groups, IRC channels and personal Blog space. I really appreciate all the efforts the Core team has put into this project. They have made the work I do more enjoyable, and less tedious. Keep up the great work! -- Our newest site for the community: CakePHP Video Tutorials http://tv.cakephp.org Check out the new CakePHP Questions site http://ask.cakephp.org and help others with their CakePHP related questions. To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/cake-php -- Our newest site for the community: CakePHP Video Tutorials http://tv.cakephp.org Check out the new CakePHP Questions site http://ask.cakephp.org and help others with their CakePHP related questions. To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/cake-php
