At the firm I work for, we recently made the switch from Zend Framework to Symfony. After evaluating the pros and cons of the available, and established, PHP frameworks (namely Zend, CakePHP and Symfony), we settled on Symfony for its pragmatic approach to development, ORM inclusion, and admin generator–being able to build a CMS around our database schema with just a few commands has proven an invaluable time saver so far. It also has a fairly robust developer and plug-in community.

One rather large factor we overlooked in adopting Symfony, however, was its documentation. At first glance, the example-driven approach they take seems sufficient. Rather than invest effort in documenting all framework components at their lowest level of complexity, they chose to aggregate components and document them through a sample application, from start to finish. Even after only a month or so of use, this approach has fallen far short of what a good framework needs in terms of documentation, and more pointedly what Symfony deserves.

Most frameworks that I’ve worked with choose to document components at the simplest level, building examples around say specific function calls like $sf_user->setFlash(), outlining the complete list of ways such methods can be called, and providing tips for their use. This works well because it makes few assumptions about how any one developer is going to use this piece of the framework. Other popular SDKs and frameworks, from Zend to .NET, take this approach. It should, after all, be the end-developer’s job as a good programmer to stitch components together. High-level examples that do so for us have only limited use beyond a beginner level and, when the only form of documentation, and an anemic one at that, lead to much time spent searching through API docs (generated from short code comments) and around Google for answers, often to questions about simple usage.

To the latter point about searching Google, a lack of framework-provided documentation may not be a problem if developer community contributions fill that gap, and that contributed content is easy to find. That’s just not the case with Symfony. Most answers to searches on Google, in my experience, either refer to deprecated documentation on the Symfony site, or blog and forum posts, which require additional time to abstract away proper usage from the specific implementation of the original author (if their questions are even useful and timely to begin with). In the best possible scenario, this is a matter of SEO, which should make solving this even easier. But documentation discovery now is abysmal.

With Symfony 2.0 on the horizon, slated for release some time in 2010, I really hope they change their documentation story–I’ve even e-mailed the release manager for 1.3/1.4 requesting as much. It’ll be a rather large undertaking as there’s quite a bit of functionality, to the framework’s credit. But if this issue isn’t resolved, I could see it preventing adoption by anyone with realistic documentation expectations looking for a mature PHP framework.