So, I LOVE the Zend Framework.  I love it so much, in fact, that I’m a ZendFramework Zend Certified Engineer.   However, I have one rather large gripe about ZF and that’s its documentation.  At first glance, and even when you first start using it, the documentation seems rather good.  It covers lots of salient points and always gives you the quick and dirty way to get started.  The problem with it is that while the breadth of the documentation is very wide, it isn’t deep at all.  Simply put, the documentation is good if you’re doing simple things.  If you want to do anything complex at all, it’s fairly useless.  There’s a pattern I find myself following whenever I delve into a piece of ZF that I haven’t used before.

  1. Check out the ZF Documentation.  See if it answers all your questions
  2. Do a search on Google to see if anyone else has used the component you’re wanting to use in the fashion you want to use it
  3. Check out the ZF Reference API
  4. Crack open the ZF source code

Generally speaking, if you’re willing to spend the time to follow these four steps, you can figure out what you want to do.  The biggest problem with this is that sometimes after investing the time you realize that the coponent you’re researching doesn’t do quite what you want.  Frustrating!

Now, my wife always says you shouldn’t complain about something unless you have a solution to offer or are at least willing to help with the problem.  So, my solution is to write better documentation!  OK, that’s a no brainer.  I think the biggest frustration I have with the documentation as it stands is that there seems to be pieces missing when you’re reading it.  For instance, if I want to write a Plugin for the MVC components, there’s documentation that kind of outlines how to do it, but not really.  You really have to dig to figure it.  Now I know that sometimes digging through source code and trial and error coding is a great way to learn stuff but sometimes I just want to take a peek at the documentation and say “Oh! That’s easy!”

Here’s the kicker.  ZF is a very well designed.  Generally speaking, it will do what you want it to do.  It’s just the figuring it out part that is the issue.  And yes, all you trolls and haters out there, I use the documentation on an almost daily basis.  I recognize that what is currently there is good.  I even recognize that for a free product it’s even better.  Having said that, you need to acknowledge that a for profit company is tooting it’s own horn over ZF.  They have a team of paid developers working on ZF as their full time jobs.  I think that they also need to apply that method to their documentation for ZF.  It’s the logical next step to making a great framework even better.