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
begin:vcard
fn:Reinhard Haller
n:Haller;Reinhard
org:INTERACTIVE Computer Systems GmbH
adr;quoted-printable:;;Hermann-Hesse-Str. 5;Kirchheim b. M=C3=BCnchen;Bayern;85551;Deutschland
email;internet:[EMAIL PROTECTED]
title:Dipl. Inform.
tel;work:+49 89 904885-13
tel;fax:+49 89 904885-22
tel;cell:+49 171 8022551
x-mozilla-html:FALSE
url:http://www.interactive-net.de
version:2.1
end:vcard
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
