Hi, As started on Twitter with @arno_u_loginlux, we think that the ezc / azc documentation can be improved in several ways.
As an end-user of this library / framework, I like the spirit of it and the way you can quickly adopt a component and use it in your software. However, regarding the documentation, for more than one year that I'm using mostly all components and I think we can complete it / improve it. I list here my thoughts about the documentation and you may feel free to add or challenge each point. In my opinion, each component have to get the following piece of information (if it hasn't yet) : - a schema : a visual way to understand the concepts underneath. We get it one for MVC which was cool because it's I guess the most complex one but I think it's not enough. - a list of examples, which can be like the PHP documentation, user contributed. The aim is to provide example of the real life or specific use that are not specified in the built-in specification. - a method that can be used to easily debug the code. Typical dev does not want to get in the ezc code but just use it. It's a bit problematic to know if there's a real bug inside the component or if it's a bad usage we are making of it. For example, I use PersistentObject and I would like to know why the find query returns me nothing. In the documentation, there's no clue to that could help me to resolve my probleme. And also, there's no way to print the $q->getQuery() without hacking PersistentObject. Maybe we must consider the fact to create a false dependancy to Debug, disabled by default. By resolving this, I guess we will increase the number of user. I know that it is a significant effort on documentation but it will have a great effect on users. -- Maxime maxime.tho...@wascou.org | www.wascou.org | http://twitter.com/wascou
