Certainly the PHP manual is an excellent example to copy. But the PHP manual is full of much more detailed explanations... I should say that it HAS some explanations. If your "discuss" feature could lead into some true augmentation of the documentation, that would really be wonderful. But I don't think I'd use the term "discuss." Maybe "explain" or "comment on" or "add documentation for" -- the idea being that the Cake API needs more explanations by people who actually understand what's going on.
Right now, sad to say, I find this level of explanation to be almost entirely lacking in Cake. And so I look at the code, but the code isn't even commented, except for some banner-style comments telling what a function is supposed to do. Sigh. I often feel like I'm flying blind, trying to guess where the runway might lie beneath the clouds. Sometimes you just really want to land, know what I mean, without having to guess all the time. Maybe I should feel flattered that the authors think I'm so smart that I can figure everything out without documentation. All I can say is that I used to think I was smart, but now I'm actually smart enough (or just old enough) to know that I'm not all that smart. I find Cake difficult to learn in depth. I have achieved some good, even impressive results using Cake, but I wouldn't say the development was easy, or by any stretch of the imagination "rapid." If I really did have something like the PHP manual for Cake, I think I could be ten times more productive with the framework. By comparison, I've been coding in PHP for about ten years now, and I still use the manual quite frequently. I used it today to refresh my memory on rand() and ucfirst() and strtolower(). PHP has a lot of functions, and C/C++ uses different names for most of them; how am I supposed to remember all of this basically meaningless stuff without a reference? Fortunately, PHP's manual, once you learn how to use it, and understand a few quirks, is about the best example of documentation I know of. Since I'm ranting, I guess I'll just continue right on to the bitter end. At the considerable risk of pissing some people off, I think that if there aren't enough writers available to document Cake, then maybe some of the developers -- at least one developer -- might consider taking time off from adding to the framework in order to document what already exists. Because right now, and forgive me, that's what's really missing. And I know I'm not qualified to take on that job, because I just don't understand Cake that well yet. </rant> --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
