incubator-zeta-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gaetano Giunta <giunta.gaet...@gmail.com>
Subject Re: [zeta-dev] Documentation
Date Tue, 11 Jan 2011 21:15:16 GMT
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.
>


Mime
View raw message