Reinhard Poetz wrote:
While Upayavira and I were discussing the documentation, we also came across the
question, where we should put the documentation of blocks within our navigation
structure. To keep things easy for now, we propose following:
- Core blocks - non-core blocks - external blocks
*Core blocks* are technically independent from Cocoon but as they will be
important for many (most) of our users, they should show up very high in our
documentation.
This is necessary because users will not necessarily have grasped the 'blocks'
system before they start researching how to handle forms, for example. They need
to find "form handling" very high up in the Cocoon documentation. To treat it as
"just another block" would mean it would get lost in the midst of quite a few
minor Cocoon blocks.
The blocks that we consider as core blocks are Cocoon Forms, Javaflow and the XML-Templating block.
+1
*Non-core blocks* will be documented within their own documentation repository.
We already have two repositories: global and 2.2, so adding others for the other
blocks doesn't make the docs system too much more complex. This way, we would
have, for example, http://cocoon.apache.org/blocks/portal/1.0/ as the place for
all Portal documentation.
The first priority of this project is to document the Cocoon core, and the Core
blocks - maybe the Portal block is an exception here as it alreay has a lot of
users. For this purupose I will set up a seperate doc repository for the
portal block.
All other non-core blocks can be documented and handled afterwards. Otherwise
the workload becomes way too high.
Agree, but I think we should divide the "non-core" blocks further into supported and unsupported blocks. Where supported means that a number of developers explicitely (in a vote) have stated that they support the block. The portal block is obviously supported, but we have a number of blocks that seem to be more or less abandoned one man shows.
Agreed.
*External blocks* are blocks that are currently hosted somewhere else than in
our SVN and we want to link to them. This section contains a list with links to
those blocks.
WDOT?
[Please let's concentrate on the 'documentation of blocks' part here. If nobody beats me, I will start a separate discussion about cleaning up Cocoon very soon.]
Sounds excelent!
Thanks!
--
Reinhard Pötz Independant Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}web(log): http://www.poetz.cc --------------------------------------------------------------------
