On Jun 24, 5:33 pm, floob <[EMAIL PROTECTED]> wrote: > I've been going at cake for a bit over one month, and I've developed a > love/hate relationship with it. I apologize if this is a rant ... > cake documentation is a touchy subject for me, and I believe my > experiences may help you. > > Understanding CakePHP has been an uphill battle the whole way, but it > is a wonderful tool with great potential. My biggest problem (by far) > with cake is a lack of adequate, up-to-date, advanced documentation. > The book is getting better every day, but I'd like something a bit > deeper.
What kind of advanced documentation have you found missing. Do you have any examples of things missing. When creating a general documentation resource such as the book, there is a balance that must be struck between being too simple and far too complex for new users. I think the docs team is doing a great job at handling that right now. However, I am personally interested in what kind of advanced docs you are lacking. > Specifically, I would like to see a lot more code comments, > /everywhere/. Seeing more live examples and tutorials would be > helpful, too ... But when I don't grasp a concept, and no API, > CookBook, GoogleGroup or random Blog discusses it sufficiently, I am > forced to go digging through hundreds to thousands of lines of > (mostly) undocumented code to understand it. Don't get me wrong, I > enjoy reading code in general, and would /like to/ enjoy reading > Cake's core code. I just don't believe I should HAVE to take apart > the car to learn how to drive it. Another resource you might find very helpful for figuring out use cases and expected results are the core tests. They are basically living examples of how the developers want the code to work. So go through the tests, for the classes in question and find out how the authors planned on it being used. > It would help things tremendously to be able to read notes from the > developers: what they where thinking, what complex code segments do, > how the developers intended certain methods to be used, how objects > interact with each other, why something was done how it was, etc. > Sort of an extension to the API, maybe an order of magnitude bigger > :). Documenting at the lowest level would allow you to breed more new > experts, giving anyone the chance to fully and easily absorb cake's > inner workings (and write knoledgeable tutorials, and contribute back, > etc.). Writing tutorials and examples yourselves is fine ... helpful, > even ... but for an open source project especially, at this point it's > like putting a peephole in a giant black box. The notes are available if you checkout from SVN using svn blame and svn log you can find out why almost every change was made to the framework. Inline documentation can't match that. I've never seen a project that had the type of documentation you state you would like to see. If you have some examples I would love to see them. I've seen a number of projects that have -no- documentation. I think documenting every line and every change is excessive and can easily lead to outdated information / bloat which defeats the purpose of documentation. > Please accept my criticism knowing that I hold you in the highest > respect. If I didn't think it were worth it, I wouldn't have > responded. Thanks to all the core developers for your hard work on > this great project. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "CakePHP" 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 -~----------~----~----~----~------~----~------~--~---
