You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@cocoon.apache.org by Reinhard Haller <re...@interactive-net.de> on 2007/06/01 10:09:27 UTC
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
Re: Cocoon Productivity
Posted by Reinhard Haller <re...@interactive-net.de>.
Reinhard Poetz schrieb:
> Reinhard Haller wrote:
>> 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.
>
> What can we expect from a beginner, when we write documentation?
>
> - Does he know how the request-response-cycle of the http protocol
> works?
> - Does he know what XML is?
> - Is he able to read (and write) XSLT?
> - Does he know what a servlet container is?
> - etc.
>
Cocoon started as an XML-based publishing system. XML and XSL are the
basics to start with, servlet and other Java related technologies are
implementation specific for cocoon, http is also a base technology for a
web framework (I suppose this is the most common use).
>> Compare this to tutorials for Netbeans, Eclipse or the JBoss IDE.
>
> hmm, those pieces of software are GUIs and not server-side applications.
agreed. I referred to the style how the tutorials are organized and
presented.
>
>> 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.
>
> I wouldn't say that they are unrelated but I agree with you that there
> is no use case behind them.
>
>> 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.
>
> What's missing? Where did you get stuck?
I didn't get stuck, my problem is the resolution of the monitor. It
takes much more time to switch between 5 windows than with 2, i.e. if
the tutorial contains all needed stuff to proceed you switch only
between your IDE and the tutorial. In all other cases you open dozens of
additional windows with doumentation stuff, try to combine all and are
still insecure if you are on the right track (even a simple typing error
may be a fatal one). Don't forget: most of the users want to publish
their XML-content and not discover the wonderful world of JAVA IDE's,
AS's, J2EE etc.
>
>> Choose a real production application server instead of the bundled
>> Jetty. Explain if it works with Plugins (WTP/JBoss IDE) and how.
>
> IMO that's out of the scope of Cocoon. If we start to explain the
> deployment in a Bea weblogic server someone will ask, how those things
> work in IBM websphere, etc.
> Cocoon is a web applications and we produce web archives (.war) that
> can be deployed into any complient servlt container. Having a war, you
> can use one of the illustrated tutorials of those containers to deploy
> your stuff there.
>
Good argument. If the deployment for all compliant servlet container is
identical, what's the problem to show it for a specific one?
>> 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.
>
> That's an awful lot of work, believe me.
I know it. Nonetheless I believe it's better to document 1 tutorial that
way than publish a bunch of insider tutorials. The acceptance of first
time cocoon users is the reward for the work.
>
>> 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.).
>
> For the reasons explained above I don't think it is a good idea to put
> IDE screenshots into the tutorials. Maybe putting in the result
> screens is helpful.
One of the cocoon problems to gain more users is the difficulty to fit
into the mainstream IDE/framework scheme. Showing how it fits into an
IDE is the first step to do it better.
>
> It would be great if some native-speaker could do a screencast of the
> 4 tutorials. That would be even better than putting in screenshots IMO.
>
>
Let's start. Maybe this is also an answer to the work needeed
documenting with screenshots.
Reinhard
Re: Cocoon Productivity
Posted by Reinhard Poetz <re...@apache.org>.
Reinhard Haller wrote:
> 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.
What can we expect from a beginner, when we write documentation?
- Does he know how the request-response-cycle of the http protocol
works?
- Does he know what XML is?
- Is he able to read (and write) XSLT?
- Does he know what a servlet container is?
- etc.
> Compare this to tutorials for Netbeans, Eclipse or the JBoss IDE.
hmm, those pieces of software are GUIs and not server-side applications.
> 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.
I wouldn't say that they are unrelated but I agree with you that there is no use
case behind them.
> 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.
What's missing? Where did you get stuck?
> Choose a real production
> application server instead of the bundled Jetty. Explain if it works
> with Plugins (WTP/JBoss IDE) and how.
IMO that's out of the scope of Cocoon. If we start to explain the deployment in
a Bea weblogic server someone will ask, how those things work in IBM websphere,
etc.
Cocoon is a web applications and we produce web archives (.war) that can be
deployed into any complient servlt container. Having a war, you can use one of
the illustrated tutorials of those containers to deploy your stuff there.
> 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.
That's an awful lot of work, believe me.
> 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.).
For the reasons explained above I don't think it is a good idea to put IDE
screenshots into the tutorials. Maybe putting in the result screens is helpful.
It would be great if some native-speaker could do a screencast of the 4
tutorials. That would be even better than putting in screenshots IMO.
--
Reinhard Pötz Independent Consultant, Trainer & (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org
RE: Cocoon Productivity
Posted by Robin Rigby <ro...@gondolier.org.uk>.
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
RE: Cocoon Productivity
Posted by Christian Schlichtherle <ch...@schlichtherle.de>.
Hi,
> Since most people curently are working with an IDE (Eclipse
> ...), in a basic tutorial we need also a chapter regarding
> the setup of a Servlet Container for debugging, testing and
> deployment of our cocoon apps within this environment. If the
> tutorial describes how to do it with Jetty as with any other
> application server I've no problems.
I do not know if this is already addressed in 2.2, but for easier
integration in JEE web apps, it would also be required to have a Cocoon
Servlet which does not take any parameters, just like Sprint for example. At
current (2.1), the Cocoon Servlet takes lots of scary parameters which may
or may not change between versions. This is a burden when upgrading a web
app to a newer version.
Kind regards,
Christian
Re: Cocoon Productivity
Posted by Reinhard Haller <re...@interactive-net.de>.
Hi Derek,
Derek Hohls schrieb:
>
> PS I think its a little unfair to Jetty to imply its not production
>
agreed. My point about Jetty is the integration within the cocoon
distribution.
Since most people curently are working with an IDE (Eclipse ...), in a
basic tutorial we need also a chapter regarding the setup of a
Servlet Container for debugging, testing and deployment of our cocoon
apps within this environment. If the tutorial describes how to do it
with Jetty as with any other application server I've no problems.
Greetings
Reinhard
Re: Cocoon Productivity
Posted by Derek Hohls <DH...@csir.co.za>.
Reinhard
I agree that the "tutorial" is more a barebones walkthrough of some
key
features - but it serves its purpose for that.
I also think that the approach you outline needs to be taken in
distinct steps:
1. Install and configure Cocoon (might differ by environment or OS)
2. Server-specific steps
3. Eclipse integration (or alternatives)
4. Working with Maven
5. Case study for some type of website (arguably anything you pick
here
will be limited from any one person's perspective)
6. Extra options (plug-ins?? related technologies)
This is because in a team environment, not everyone does everything and
handling these things in steps allows for "separation of concerns".
So we arrive back at the usual question of "so this is a nice idea, but
who
will actually do it??"
Derek
PS I think its a little unfair to Jetty to imply its not production
capable - see:
http://docs.codehaus.org/display/JETTY/Jetty+Powered
>>> Reinhard Haller <re...@interactive-net.de> 2007/06/01
10:09:27 AM >>>
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
--
This message is subject to the CSIR's copyright, terms and conditions and
e-mail legal notice. Views expressed herein do not necessarily represent the
views of the CSIR.
CSIR E-mail Legal Notice
http://mail.csir.co.za/CSIR_eMail_Legal_Notice.html
CSIR Copyright, Terms and Conditions
http://mail.csir.co.za/CSIR_Copyright.html
For electronic copies of the CSIR Copyright, Terms and Conditions and the CSIR
Legal Notice send a blank message with REQUEST LEGAL in the subject line to
CallCentre@csir.co.za.
This message has been scanned for viruses and dangerous content by MailScanner,
and is believed to be clean.
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org