January 19, 2009

Cake documentation

Everyone but the cake team knows the cake docs suck huge. Obviously written by someone with a solid understanding of cake internals and pretty sparse at the best of times. Add to that the api docs often don’t even list all the functionality for a class (usually due to parent objects exposing functions) and you end up having to search for something obvious and simple like:

$this->modelName->getAffectedRows();

which obviously tells you how many rows were affected by your last query. Search the cake docs and find nothing. browse the api and find nothing. You’re left with following the object tree through code or google.

this is but one of a million tiny things that should be expressly documented at least in the API, which take time to find answers for and I think likely annoys new cake deveopers—possibly right out of cake.

symfony made huge strides in growing its developer base because of its great documentation, and to my knowledge i never went looking for a function call in the api and was unable to find it. these things matter when you’re in the learning curve, and they matter when you need to find information rarely used.

cake would do well to address this.