I've met a guy two years ago that insisted CakePHP's documentation is crap. Turns out he was looking at the API. The API is the first link when you click on the documentation link, contains sublinks for all versions and even worse "book" can be mistaken for something like a paper book instead of the documentation so perhaps people don't normally go there. If the links were to say for example first "Cookbook (documentation)" and then "Framework API" I doubt anyone would accidentally go to the API instead looking for the docs.
Once on the docs, I personally find them pretty straight forward, covering just about everything you'll need to work with the framework. It's been a while so I don't particularly remember now, but when I first looked for a framework (6 years ago?) I went through the first parts of the documentation of each framework and ended up with cake because the documentation, the principles and the workflow made more sense to me. The blogging tutorial was great to follow along and learn more of the framework. I also liked the conventions over configuration pattern and the fact that best practices are always in use, displayed all through the docs. This for the novice programmer can be of big help. I can't remember if I googled for a comparison of frameworks, but I doubt if I did, knowing how erroneously opinionated and biased these top posts can be. Still lots of users start out with such comparisons and cake is definitely failing there since it has no hype. If you'd change the name of cake 3 to something else, I bet it would have been welcomed completely differently. Back to the docs. Most people plainly browse by the title and first paragraph of every topic and think they've read it as a whole. Could that be considered a fault of the docs? Do we have too much information on the same page instead of small parts of it in several pages? That's probably something that would requiring user testing to be certain. But if we consider some "rival" docs, does http://laravel.com/docs/4.2/routing (which is like the 3rd link in getting started) make any apparent sense for a beginner of the framework at first site? I doubt it. Let alone there is no starting guide the way cake's blog tutorial is, to get you through a first working application. I have a feeling that most people who have misconceptions about cake are total beginners (with PHP and programming concepts in general or frameworks) and expect a framework to think ahead of them and do everything as they particularly need it without touching the code. They might start with cake and end up being frustrated out of their own luck of abilities, but blame cake. You see it from time to time in stack overflow. While we can't disregard complete novices (and try to be helpful to them when they have stupid questions), I don't think it should be the purpose of the framework. One other factor is that cake is so old that it carries parts of a very old legacy. Search google for "cake vs symphony" to get top results of 2008/2009. Things have changed so much since then, but if you're a true beginner with no knowledge it is hard to read through these articles and value them or the comments without being wrongly influenced. Can we battle that? We could if we could get new articles about the awesomeness of cake 3 coming out. We should also point out how many big applications are written, supported and still maintained over the years. The fact the framework survived 10 years in a such ever changing environment means big and has the advantage that there is less chance of disappearing overnight, making for an investment that will pay out. We need to make these points more apparent. Finally, the first impression counts. Always have the site always look good and new from a design standpoint, as well as the baked application's template (which is already in process for 3 and I'm glad it is). -- Like Us on FaceBook https://www.facebook.com/CakePHP Find us on Twitter http://twitter.com/CakePHP --- You received this message because you are subscribed to the Google Groups "CakePHP" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/cake-php. For more options, visit https://groups.google.com/d/optout.
