cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Reinhard Haller <reinhard.hal...@interactive-net.de>
Subject Re: Cocoon Productivity
Date Sat, 02 Jun 2007 08:51:15 GMT
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


Mime
View raw message