cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Robin Rigby" <ro...@gondolier.org.uk>
Subject RE: Cocoon Productivity
Date Fri, 01 Jun 2007 09:18:30 GMT
IMHO, as one who started cocoon earlier this year, the greatest need is for
'meta-documentation'.  May I call it that?

The simple things are clear and elegant.  For the rest, there are hundreds
of samples and masses of good documentation but it is all in little bits in
separate places.  Even within the official documentation, the bits for a
simple form-flow-database project come from many different pages.  There
must be a dozen or more block / component sets that can "work" but perhaps
only three or four that an up to date, experienced developer would
recommend.

Cocoon is big enough and complex enough now to need its own search engine.
Something that

+ knows where all the documents and samples are and which software
environments they work in (or not).
+ knows about all the blocks and components; how they overlap; how they
compete or cooperate with each other; which are new, stable, deprecated,
etc.   
+ maintains a list of tasks that developers may be asked to carry out in the
real world; how to glue the little bits together to make something really
useful.
+ links it all together in a Perl sort of way ["There is more than one way
to do it."] with some kind of discussion of why one way may be better than
another in a particular context (otherwise there is no learning).
+ helps sort out keyword conflicts, for example where a technical word is
also a word in common use, or is used with different meanings by different
blocks.  

Someone wrote about a 'wizard' but that may offer a single solution based on
criteria that may not be general enough.  As a beginner and a serious
student, I would like to see the options, understand the pros and cons,
choose one for myself.
 
Robin Rigby
 

-----Original Message-----
From: Reinhard Haller [mailto:reinhard.haller@interactive-net.de] 
Sent: 01 June 2007 09:09
To: users@cocoon.apache.org
Subject: Re: Cocoon Productivity

Reinhard Poetz schrieb:
>
> I have been working on 
> http://cocoon.zones.apache.org/daisy/cdocs/g2/g1/1370.html. I hope 
> that it helps.
>
said first I have no knowlwedge of maven or cocoon2.2.

Your tutorials for me are typical examples of the problems regarding the
current cocoon documentation.

It's very valuable if you already know why and how to do what you want. It
helps for nothing if you are a real beginner.

Compare this to tutorials for Netbeans, Eclipse or the JBoss IDE. Instead of
showing what you do and possibly why you do it, you choose a set of very
simple unrelated topics to achieve a very short and pregnant documentation
for people which already know what they do.

Simply put the screenshots of your Eclipse in the documentation, this
explains much more than your text. 
Document your example (your first Cocoon application ...) from the very
beginning, i.e. installation and setup within eclipse (from svn/from
distribution) including the setup for the application server if needed. 
Choose a real production application server instead of the bundled Jetty.
Explain if it works with Plugins (WTP/JBoss IDE) and how.

Providing the community with a non trivial tutorial that covers a website
with structured templates for content, navigation and metadata, combined
with a real world error handling would help to get new users an impression
of the developement cycle and the structure of a cocoon application. If you
also explain how to manage the different versions (cocoon, the cocoon
application i.e. sitemap, the website templates and the web content) in one
or more svn repositories then we have a sound base to start with and
additional documentation can refer to this tutorial.

With a screenshot based documentation everyone is able to see if there is a
difference between the tutorial and his own computer and check out why there
is a difference (other versions etc.).
 
Greetings
Reinhard




---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org


Mime
View raw message