Solved thread

This post is marked as solved. If you think the information contained on this thread must be part of the official documentation, please contribute submitting a pull request to its repository.

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.



5.1k
edited Apr '14

Hi gresakg,

There have been quite some enquiries already regarding this subject. E.g. see: https://github.com/phalcon/cphalcon/issues/1712

Also helpful are the stubs: https://github.com/phalcon/phalcon-devtools/tree/master/ide and the Phalcon 2.0 code written in Zephir: https://github.com/phalcon/cphalcon/tree/2.0.0/phalcon

And an alternative, more informative API browser exists at http://phalcon.agent-j.ru/

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.



18.8k
Accepted
answer

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



431

Hi guys! Thaks for your responses. Renski, yes I found pretty much everything you are mentioning. Nikolaos, I can see you can get answers on the forum quite fast and I guess that's the best option. I