I don't think that someone has to be appointed to do it. Everyone can
contribute by writing an improvement, opening an issue in JIRA and
attaching the improvement to it.
As to the book you mentioned, I think the initiative came to a halt
again, shortly after it was started.
Uli
Newham, Cameron schrieb:
I think we are all in agreement that the documentation needs a radical overhaul
(and lots to be written).
The next question is, who is going to do it?
A while ago someone proposed a book on T5. A small group from here organised a
separate discussion group and went off to work on it (I have no idea how it is
going. Does anyone know?)
Maybe a similar thing should be done w.r.t this current issue?
c.
-----Original Message-----
From: Borut Bolčina [mailto:borut.bolc...@gmail.com]
Sent: 21 January 2009 08:58
To: Tapestry users
Subject: Re: [T5] improve documentation
Hi,
also a guide/recipes/good practices/tips/chapter for converting JSP
applications to Tapestry 5 would be very welcome. At least a paragraph
clarifying questions like: "Can I have JSPs in my Tapestry 5 application or
do I have to have two web applications talking somehow to each other?", "How
to post a form from JSP to a Tapestry page or vice versa?", ...
A guide on clustering. I know this info can be found in many locations on
the net, but writing it in Tapestry documentation would imho greatly improve
the credibility of the framework for "serious" web applications. I feel
tapestry is missing the scope in the market. It is not advertised in any
way, nor as a framework which one can use to quickly make a simple news
site, as other frameworks (non java) are better at that (so I hear), nor as
a framework which is best for large teams and large applications. Just look
at the web page for Zend PHP framework (http://www.zend.com). Which page do
you think management like more, zend's or tapestry's? Unfortunately
sometimes (too often) the arguments of power outweight the power of
arguments and the consequence is, well, "We will use the framework which has
more flashy homepage!".
The community, us, must prove that a simple web application (some forms,
administration pages, publishing news, social "crap", etc) can be done
without having a PhD in Computer Science. Tapestry relies much on convention
over configuration paradigm, that is why the documentation must be excelent.
Say, for example
http://tapestry.apache.org/tapestry5/tapestry-core/ref/org/apache/tapestry5/corelib/components/Form.html.
This page is clearly frightening - look at the first paragraph. So many
events and none/few of them has a decent explanation/usage scenario/example.
IMO all of them should be properly documented or not mentioned at all.
The authorization should have a chapter! Tapestry is a very powerful
framework and as such the same thing can be done differently, BUT...why
should one have to spend days/weeks to implement a decent
authentication/authorization system? There should be a guide for common
scenarios like form based authentication. Of course one can hunt for example
projects and study the guts of them, which in the end is very rewarding, but
time consuming. Newcomers should have clear goals on how to implement such
things, without jumping to the wiki and other places and fighting the
dependency incompatibilities.
-Borut
2009/1/13 Ulrich Stärk <u...@spielviel.de>
Hi all,
Tapestry's current documentation is very complete, covering almost
everything a developer needs to know to be productive with Tapestry.
Unfortunately this documentation is clustered across several locations thus
making it hard to find information and very hard for beginners to get going.
Sometimes even I am annoyed because I don't find the information I'm looking
for at the expected place. There is the official user guide, which is no
guide in the actual sense of the word but merely a collection of topics
using Tapestry-specific vocabulary as the topics, making it hard for a
beginner to get started. Then there is the tutorial that gets you started
with Tapestry but doesn't go deep enough to know the name of the topic to
look for in the user guide when a problem arises or more information on a
subject is needed. Thirdly, there is the wiki that contains numerous
examples on how to solve common use cases with Tapestry. And lastly there is
the component reference that not only contains documentation for a specific
component but also contains examples on how to use them to solve common use
cases. Today for example, someone on the users mailing list asked for how to
have some kind of a "dynamic component". He wanted to display a certain
component based on the outcome of a function he wrote in his page class.
This question has come up before on the list and because of the "Static
Structure, Dynamic Behavior" paradigm - which is a key principle and is not
mentioned in the documentation but at the bottom of the start page - the
solution is to use the Delegate component with blocks. In the Delegate
component reference documentation there is an example covering exactly that
use case. But it seems that the user wasn't able to find it - either he
didn't look at all or more probably, he looked in the wrong place. How could
he possibly know, that the solution to his use case is documented in a
component named Delegate?
Because I think that the current arrangement of the documentation makes it
hard to grasp the concepts of Tapestry, especially for beginners, and to
quickly find the information one seeks, I propose the following steps to be
taken to improve the documentation:
1. Re-arrange the current documentation to not just be an alphabetically
ordered list of topics but instead to be some kind of guide to Tapestry.
Group topics that belong together, start with basic topics and end with
advanced ones.
2. Print a short description of the purpose of a component next to its link
in the component reference.
3. Integrate the various documents into a coherent documentation that
follows a red line, beginning at the basics and ending with advanced topics
like manipulation of internal services. The tutorial could be used as a
starting point.
4. Extend the Tapestry Cookbook. Move solutions to common use cases from
the wiki (if they meet certain quality criteria) and the component reference
there.
Steps 1 and 2 are easy to realize, steps 3 and 4 need more work.
What do you think? What are your experiences with Tapestrys documentation?
Do you think the proposed steps would lead to an improvement? What other
aspects of the documentation do you think need improvement and how could
they be improved?
Cheers,
Uli
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org
For additional commands, e-mail: users-h...@tapestry.apache.org
**************************************************************************
Experience the British Library online at www.bl.uk
The British Library's new interactive Annual Report and Accounts 2007/08 : www.bl.uk/knowledge
Help the British Library conserve the world's knowledge. Adopt a Book. www.bl.uk/adoptabook
The Library's St Pancras site is WiFi - enabled
*************************************************************************
The information contained in this e-mail is confidential and may be legally privileged. It is intended for the addressee(s) only. If you are not the intended recipient, please delete this e-mail and notify the postmas...@bl.uk : The contents of this e-mail must not be disclosed or copied without the sender's consent.
The statements and opinions expressed in this message are those of the author and do not necessarily reflect those of the British Library. The British Library does not take any responsibility for the views of the author.
*************************************************************************
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org
For additional commands, e-mail: users-h...@tapestry.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org
For additional commands, e-mail: users-h...@tapestry.apache.org
