This blog post is an interesting read. Though, I do have some complaints and feedback of the documentation on cakephp, still, I cannot say no one is doing a great job. I believe cakephp’s documentation [http://book.cakephp.org] is always updated from time to time, so there’s a chance you will see what you are looking for.

I don’t think coders are lazy. IMHO, sometimes, coders can’t afford to have time to make experiments with cakephp.

There is a lot of automagic that goes on and if you’re trying to learn programming and Cake at the same time (as I am) there can be a lot of reading to fill in the missing pieces that are assumed as common knowledge in the documentation or hidden when examples use scaffolding.

Also while there are a lot of great blogs, forums and groups (and I use them extensively) I’d suggest that those should not be considered documentation in any formal sense because they lack a coherent structure and reflect a variety of (sometimes contradictory) coding practices.

In the end the quality of documentation will influence the. size and growth rate of the user base so documentation is worth investing in.

1) PHPDocumentor is a tool that parses all javadoc-style comments out of your code and puts them into navigable HTML files.

2) TextDox is another little hottie. It creates documentation by parsing out the names of your unit test suite names & method names.
For example, if you have an AccountTest class with a cannotHaveANegativeBalanceTest() method and a canHaveMultipleOwnersTest() method, you will end up with a document that says:
Account:
– Cannot have a negative balance
– Can have multiple owners

How do you run PHPDocumentor & TestDox?
Use Phing, or Ant. Both are free and fairly simple to learn & use.

Of course, only documenting the “how” of a project isn’t always enough.
If you have a distributed team, or if you’re developing an open-source product that any Joe Schmoe can download, they’re going to need access to the original conversations. To be most effective, they need to know why things are the way they are. That’s not covered by any auto-generated documentation, and I believe this is where screencasts & tutorials come in handy.

>>I sometimes wonder if you can really say that a piece of code works properly if it
>>passes all the unit tests associated with it.

Unit tests only prove that it does what you said it would do, not that it does the *correct* thing.
It’s up to the Product Manager / Owner to define *correct*.

Fortunately, I’ve had a lot of experience both with designers and developers and one great errors of the stereotypical developer is “What? I get it, why don’t you?” That’s no different than zero documentation because you don’t get why people can’t just read your code and reverse engineer it themselves. It feels like that’s your primary argument here. You’ve just defeated the primary benefit of leveraging a framework. You’re forcing the end user to work at the low level instead of the high level development promised by use of frameworks.

I agree that the documentation does exist, albeit… contradictory, incomplete, and unorganized. In less than five minutes, I’m sure we can find a long list of frankly incorrect documentation in the cookbook. At least now we can go through and submit corrections. Prior to that, there wasn’t much you could do. If you need specific examples, I believe at last look prior to the cookbook going down, all the find documentation was using the findAll, etc. A browse through the bakery also yields entries which look fine until a few comments down the line someone with experience points out this is a completely errant entry running counter to cake convention or simply poor solutions.

I approached cake as an experienced developer looking to make life simpler for some basic projects. I did find the existing documentation situation frustrating because of the conflicts in the manual (and now cookbook) and the bakery entries inconsistent in quality. And folks new to the cake community have no idea which blogs provide dependable, quality solutions and which are hacks.

As for _working_ example code, it’s important because frankly developers are not the most articulate folks around and the description for an expected value or argument isn’t always clear.

I don’t think you’ll find other communities pointing to third party blog posts and such on independent sites as an excuse for not having better documentation. And that’s the biggest frustration for new users. While the community as a whole writes lots of informative posts and such, the authoritative voice (domain in this case) provides little or no direction on a number of critical topics.

When trying to quickly integrate this framework into an existing workflow, the experience could be significantly improved with more accurate, authoritative and organized documentation. I don’t think anyone would deny that.

Remember that most of the cake audience comes in as a developer crunched for time and looking for a solution. Successfully hooking and keeping that developer means providing a means to locate the right information quickly. You’re right to say that it is possible to locate the information with enough time and patience, but to a hurried developer looking for something to save him, it’s just silly.

Respectfully

I can’t remember when I last time asked a question on any mailing list or forum. I can google it much faster or get an immediate help from co-workers. I have no patience to wait for the answer that may even never arrive.

However I have an uderstanding for people that have different approach. You need some time to develop an answer-finding-methodology that suits you best.

My biggest problem with CakePHP’s documentation is that much of the literature is confused, and in some cases contradictory, or missing critical details. A prime example is with the ACL implementation. There are hundreds of articles on how to use it in CakePHP, but they all say something different, and some of the techniques are outdated, or have been changed since the article was written.

The ACL section in the cookbook is also guilty of this as it doesn’t cover the full scope of the ACL component and how it works together with Auth.

Another thing is HABTM documentation – again, contradictory and incomplete.

That said, eventhough it’s a bit of a headache getting through these hoops, you can always rely on the well documented API, and even the comments in the code itself are helpful. Most problems I’ve ended up solving just by reading the code of the function(s) I was trying to use. CakePHP’s source code is generally very well written and easy to follow.

The Bakery is a great resource, the cookbook is always improving, and the best part of the CakePHP documentation is that ANYONE can get involved. I’ve contributed to the bakery and have submitted stuff to the cookbook. If you learn something useful about CakePHP, pass it on!