I’ve recently been looking into various MVC frameworks for PHP, and came across the Cake framework. It’s a port of Ruby On Rails to PHP (or as close to a port as possible), emphasising convention over configurabililty. While it’s very impressive from a technical standpoint, that’s not what is so pleasantly surprising about it – plenty of open source projects have very talented programmers contributing to them, making technical prowess a starting point for OS projects, not a destination. No, what surprised me was the amazing level of documentation for the project.
Simply put, CakePhp has some of the best, most comprehensive, most relevant and best organised documentation I’ve seen in an open source project. Whenever I had a question of any sort, not only did I find documentation “related” to it, I found full tutorials specifying exactly what I needed. In addition to the great docs at their manual and wiki, the also have a full set of API documentation.
Now, many projects state that they have API documentation by virtue of the fact they have some kind of automatic document generation á la Javadoc, but in the vast majority of cases this just consists of a listing of the available objects/classes and their functions, with extremely sparse explanations of what the methods/classes actually do, how to work with them, caveats etc. CakePhp has all of this. How they convinced open source developers to spend so much time writing documentation, I’ll never understand, but I as I said, I am very, very happy to see it.
I read a blog post that evaluated a number of PHP MVC frameworks, that stated that one of the main reasons Cake didn’t top its list was the seemingly slow pace of development compared to some of the other frameworks. If this kind of documentation, which provides me with everything I could possibly need, is the result of such “slow” development, I could only wish that more open source developers would slow down a bit.