Lack of concise documentation

Hi! I think Phalcon has everything I always wanted in a framework. Everything except one thing: a concise documentation.

The documentation section is useless: instead of documenting Phalcon it explains general concepts and gives examples. While this is of a great value for beginners, it does not help experienced developers, who are only interested in how a feature works, what arguments it expects, what conventions you need to bear in mind, what are it's dependencies and configurations, what results one may expect on the output ... etc.

On the other hand, the "hidden" api section just states the classes, namespaces, members and methods almost without any explanation.

When I experienced lack of documentation in other frameworks, I just went sniffing what's happening in the code to figure out the usage. With Phalcon being written in C, even this is not possible for non C programmers.

That's why Phalcon needs a concise documentation, similar to the well documented functions in PHP. Without that I am either forced to do it your way (by tutorials), or spend insane amounts of time for figuring out how to do it my way.

The documentation is centainly lacking. It seems like it was written from the perspective of the developers who wanted to explain all the functionality - rather than from the perspective of someone who wants to know how a particular bit of functionality works.

I think the development team knows about the lacking documentation, but I'm not sure how high a priority it is - they are all volunteers after all.

With this new version of the forum, though, the community is starting to pick up, so if you have questions, this forum is a good first place to ask.

Yes we know about the documentation and we have had numerous requests to enhance it. We are also working on a new website for the docs which will allow the docs to be translated in a more efficient way.

Our top priorities at the moment are 1.3.2 and 2.0. 1.3.2 is pretty much completed and will be released shortly. 2.0 needs a bit more work in terms of documentation, tests and functionality.

Hopefully within the next month or so we will have a solid 2.0 and that includes its documentation :)

In the meantime, the forum is the best way to find answers to questionable documentation