Simone Gianni skrev:
Jeremy Quinn wrote:
Documentation would really help.
Absolutely!
I have just been working on an established project that is built from
2.2 and I could see the advantages of the new platform.
However, many perceive 2.2 as almost unusable. It clearly is being
used but the procedures are very different from 2.1 ..... the results
can be completely unpredictable ..... it will compile one minute and
not the next, this is very off-putting. If the less experienced
developers like myself cannot feel confidant with the build system for
2.2 what hope do we have of users embracing it?
IIUC, the users should not build cocoon 2.2, they will just use maven to
fetch an archetype, write their sitemaps and stuff there, configure
their dependencies, and then use again maven to build it. Maven will
fetch cocoon core, all the needed blocks, and produce a war or launch
jetty with it.
That is normally correct. Right now a user need to compile as there are
so many improvements that simplifies usage since the last milestone. But
we will hopefully get a new milestone release in the near future. This
will make it as easy as you described above to use Cocoon.
Another thing that would simplify it for developers to start work with
Cocoon 2.2 would be if we went back to have a cocoon-webapp that
actually does something.
Now we instead have the dist samples that put everything together in a
war file. But they are somewhat unstable and as I described in a
previous mail, completely unusable for sample development.
The cocoon-webapp doesn't contain any samples anymore, so a develper
doesn't have any good examples on what a Cocoon development environment
looks like anymore.
I would propose that we either add some samples to the cocoon-webapp
again or that we create some cocoon-sample-webapp to Cocoon that
contains some samples.
Sorry this is in no way intended as a personal criticism, merely a
statement of facts as I perceive them.
Same here, nothing wrong at all with the incredible work that has been
made on 2.2.
The real problem at the moment, in my opinion, are not the users, but
the *developers*. I've been using 2.2 in last 4 months, experimenting
with it a lot, but still don't know how many things work, things changes
continuously, and we (even committers) don't know what still has to be
done and how.
To my knowledge nothing _has_ to be done on the code. It is perfectly
usable as is (although there are of course room for plenty of improvements).
What needs to be done is documenting how to use it. And that more people
start to use it so that we can find bugs, stabilize it and smoothen ease
of usage.
It's not a matter of code by itself, or maven, or osgi.
OSGi is not used at all, currently.
From my PoV, the areas most urgently in need of documentation are :
A cookbook for how to develop 2.2 (as you describe)
Recipes for starting your own project.
Troubleshooting hint for solving common build problems.
Agree.
Again, absolutely, and I'd like to add also :
A clear and detailed roadmap to 2.2
When I have asked earlier no one had any outstanding items that we
absolutely must solve. What is lacking is documentation.
So what we need is a roadmap for documentation.
In some sense we have that also: one can browse
http://cocoon.zones.apache.org/dev-docs/ and see what is lacking. There
are lots of skeleton documents, so it is just to start filling in the
empty sections ;) Much of that can be done by moving documentation from
2.1 to the new documentation and correct it if needed.
It is still hard to know where to start. For me at least some kind of
documentation road map or priority list would be helpful. So that I
could start with what is most important.
/Daniel
