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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
