Yes I agree with these last 3 answers. I was imagining comments like in php.net web that show a lot of different ways to use the code in action so you don't need to go around searching for all those bits of code here and there on different blogs...
In this case if comments are needed much better to be more visible and even rated. But it's true this is not a language is a framework and it might be different the comments posted here. It's also true that being able to change directly the text it allows flexibility and improvements without the need of comments. So maybe what I wish is just to not to have to open 3 or 4 tabs every time I search to implement something new in my app. I think the documentation lacks examples. Maybe it would be great to have links within the documentation of many examples that exist and the API of the classes referenced. And if they were displayed there with javascript (hide/show) even better. Of course all this if it doesn't mean that developers have to take their time out of their work on the core code. But I thought they wanted to hear about our experiences on the book and what we think it's needed or how we would find it more useful. so just this, my opinion if it helps :) On Jan 24, 11:35 pm, "Dave Maharaj" <[email protected]> wrote: > 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 > Tutorialshttp://tv.cakephp.org > Check out the new CakePHP Questions sitehttp://ask.cakephp.organd help > others with their CakePHP related questions. > > To unsubscribe from this group, send email to > [email protected] For more options, visit this group > athttp://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
