Maxime Thomas wrote:
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.
That's a tough problem, but I concur with the last point.
To me, the way the components work often feels like blackmagick: sometimes it is logical, but more often it's just like incantations. The example spells given
in the docs are fine, but as soon as you stray a little bit from those, you're on your own - either it works at the very first try or it becomes a thankless
test/change/repeat loop (eg. sometimes a certain mix of options work, and another mix does not work, or some methods have to be invoked in a particular order).
As far as I can tell, this is at least in part a fruit of the design/architecture of the components: with the division of tasks in so many small classes and the
heavy usage of subclasses and magic methods (getters, setters etc), following the logic trough the code is not the easiest task. The upside being that more
often than not, you will be able to solve your problem by creating a subclass with a one-liner fix in a single method!
I have no real proposal to make for debugging helpers, but am interested in any
that might be given...
bye
Gaetano
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.
