cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel Fagerstrom <dani...@nada.kth.se>
Subject Re: Blocks documentation
Date Fri, 11 Feb 2005 08:40:09 GMT
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


Mime
View raw message