Re: Blocks documentation
Daniel Fagerstrom wrote:
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
Re: Blocks documentation
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. *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! /Daniel
Blocks documentation
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.
*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.
*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.]
--
Reinhard Pötz Independant Consultant, Trainer (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
