I think Fergus has it spot on here.
Most developers operate by first copying another example of something
that works, then they modify it to their own use.
As a fall back, complete technical documentation of the technology is
then needed to detail how it operates and what its syntax, grammar etc. are.
Lastly, for the more complex techniques it can be useful if a very
simple example is shown in a step by step approach to grasp the concepts
before delving into the deeper "all sing all dancing" examples.
Jonathan
Fergus McMenemie wrote:
As a new adopter of cocoon, I beg to differ from some of what
I have read regarding documentation. Referring to cocoon
version 2.1, it comes with lots and lots docs and examples. I
really do not think we are dealing with a lack of documentation
or examples. Rather it's a case of knocking what already exists
into shape. Especially the examples.
IMHO the examples need to be "rewritten" so that they function at
two levels. Firstly, they should be shiny examples of cocoon
functionality when played with via the browser. Secondly, each
example should be totally standalone in its own sitemap, suitable
for lifting from cocoon distribution and used as a template for
new users getting started with cocoon. Individually the examples
do fine at the first point, although cumulatively they are a rather
disorganised mish-mash. At the second level it is a significant
task for a new user to disentangle a demo application, that almost
does what they need, from other related demos that share sitemaps,
resources and other dependencies. I also suspect that a number
of examples reflect practices which are now deprecated. Deprecated
examples should be removed, there's nothing worse than getting
your head around one method only to be told it's a dead technique
and something else should be used instead.
The coverage of documentation is patchy, some bits are quite well
covered other bits rather poorly. When it is good it is very good.
The general overviews, concepts and simple stuff is fine, but the
detail of serializers, generators, generators and actions etc is
where major problems really start to appear. Far to vague and in some
cases unintuitive. I have not seen anyone else pointing it out, but
after a day or two I was really struck by the fact that conceptually
pipelines are not pipelines in any common understanding of the term;
rather matchers are the pipelines! This sort of thing is very
counter intuitive. Systems that are intuitive require a lot less
documentation.
On another level, and this is my experience of other leading edge
technologies, I think we/you need to consider what it is your users
really need. A well done body of documentation will always lag behind
any rapidly moving software development activity. Documentation that
is out of date is next to useless. So what do you do? Slow down the
developers and force them to support or wait for those doing the
documentation? Or accept that documentation will never catch up with
the leading edge and find another way. I think there is a second way
and that is tons of complete working, and documented examples. Such
examples should at the same time be examples of the leading edge and
best practice. A good clear and relevant example will always get you
70% of where you need to be. Having got that far you can generally
figure out the rest using the wiki and other resources.
Regards Fergus.
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
